# maki: a terminal coding agent that treats the context window as a budget

> A Rust TUI coding agent built around token accounting, tree-sitter indexing and Lua plugins, with more than a dozen model providers and an ACP mode for editors. The README is unusually candid about its own token measurements.

**tontinton/maki** — An efficient AI coding agent extendable by neovim-like Lua plugins

- Repository: https://github.com/tontinton/maki
- Website: https://maki.sh
- Stars: 1,221 · Forks: 178
- Language: Rust
- License: MIT
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/tontinton-maki

## Why the token budget drives the whole design

Most coding agents describe themselves by what they can do. maki leads with what it refuses to spend. The README opens by describing an agent optimized for minimal use of context tokens, and the first feature listed is the `index` tool, which uses tree-sitter to parse supported languages and produce a high-level skeleton of a file with exact start and end lines for each item.

The author then does something unusual and quantifies it: `index` costs 59 tokens per turn and saves 224 tokens per turn on read calls, a net saving of 165. That measurement is the design rationale stated plainly. The same treatment is given to bash output filtering through the optional `rtk` tool, which saves roughly 50% of bash output tokens, followed immediately by the observation that bash is only 12% of total token usage while reads account for 65%, so the 6% from bash filtering is worth less than the larger saving from indexing.

That reasoning is worth internalising, because it explains why the tool exists at all. Reading files is the expensive part of an agent session. A skeleton with line numbers lets the model decide whether to read a region without paying for the whole file.

## Tools that keep data out of the conversation

The `index` tool handles the read side. The `code_execution` tool handles the write side of the same problem. It uses the `monty` library to run an interpreter that has every other tool available as async functions, letting the agent filter, summarise, transform or pipe data into other tools without that data ever entering the context window. The README notes the sandbox is limited by time and memory.

This is a meaningfully different architecture from an agent that asks the model to print a file and then reads the file itself. If a tool returns 40,000 lines and the agent only needs an aggregate, the `code_execution` path means the aggregate comes back and the 40,000 lines never cost anything.

The `task` tool completes the picture. When the agent delegates to a subagent, the model chooses whether to run a weak, medium or strong model of the provider in use, in the README's phrasing, think Haiku, Sonnet or Opus. Cheap models handle routine delegation; expensive ones are reserved for the calls that need them. A `memory` tool sits alongside for long-term context, managed through `/memory` for viewing, editing and deleting memories, and the agent sometimes uses it without being asked.

Two smaller choices point the same way. The system prompt, tool descriptions and tool examples are all kept short by design. And the author is explicit that other coding agents hide information as models improve, for example the number of lines read, while maki leaves you in control of that.

## Rust TUI with a Lua plugin layer

The interface is a terminal UI built on `ratatui`, and the README is specific about the performance claims: fast startup, 60 FPS, light on memory, and no JavaScript anywhere, with the splash screen animation also using SIMD. Startup latency matters more than it used to, since agents are launched and relaunched constantly during a work session.

Extension works the way it does in Neovim. Built-in plugins live in the repository's `plugins/` directory, user plugins are collected in a discussions thread, and the Lua API is documented separately at maki.sh. A separate example configuration repository, `tontinton/makiconf`, shows what people build, including a `semble` tool written in Lua for semantic code search and an `ast-grep` MCP server for AST-based search and replace.

Subagent visibility is unusually strong here. Each subagent gets its own chat window, and you navigate between them with `/tasks` bound to Ctrl-X. Rather than hiding a fleet of parallel work behind a spinner, the design assumes you want to read what each one did.

Other interface details that are easy to miss: fuzzy search on Ctrl-F, `/btw` to run a command with the chat history without disturbing the current session, rewind on double Escape, which rewinds chat history but not code, image attachment in prompts, plan mode, 26 built-in themes, and bash invoked directly with `!`, or with `!!` when you want the agent not to know about it.

## Providers, auth paths and a TOS caveat

The provider list is long enough that most people will find their existing credential in it: Anthropic, OpenAI, xAI, Google, Copilot, Ollama, llama.cpp, Mistral, Z.AI, DeepSeek, OpenRouter, Requesty, Synthetic, Regolo, TensorX, OpenCode Zen, OpenCode Go and Aperture. Each is configured by one environment variable, with regional notes where they matter, such as `REQUESTY_BASE_URL` for the EU region of Requesty.

Two entries are worth reading carefully. Anthropic accepts `ANTHROPIC_API_KEY` only, and the README states that using OAuth is against the terms of service, with Bedrock available through `CLAUDE_CODE_USE_BEDROCK=1`. That is a constraint rather than an omission. Aperture needs no API key at all, because Tailscale handles authentication at the network layer.

There is also a free path. OpenCode Zen works with the `public` key for zero-cost models from the models.dev catalog.

Beyond the built-ins, dynamic providers let you drop an executable script into `~/.config/maki/providers/` to add a custom provider or proxy, which is the extension point for anything the list does not cover. Version 0.5.3 added a browser login flow for OpenAI using PKCE with a callback on localhost:1455, alongside the device code flow that remains the right choice over SSH or inside a container.

## Permissions parsed with tree-sitter rather than prefix matching

The permission system is the part of maki that most directly affects whether you can let an agent run unattended. The README poses the problem concretely: when the agent runs `git diff && rm -rf /`, what do you think happens in your current coding agent? The answer it gives for other tools is that they treat it as `git *`. maki uses tree-sitter to parse the bash command and work out that the permissions actually requested are `git *` and `rm *`.

That is a real improvement, because a compound command that gets flattened to its first element is a permission bypass wearing a disguise. The escape hatch exists, and disabling the system is `--yolo`, which is worth knowing about mainly so you know what not to paste.

Two safety features sit alongside it. `webfetch` calls have SSRF protection, so the agent cannot be talked into fetching internal addresses. And the bash prefix distinction between `!` and `!!` means you can run a command yourself without recording it as something the agent chose to do.

The release history shows this area being taken seriously rather than bolted on. Version 0.5.4 added folder trust, because opening a folder used to run the code that folder shipped: a clone with a `.maki/` directory would execute its `init.lua`, load its `.env` including `BASE_URL` which decides where your API key goes, and start any MCP servers it named, all before your first prompt. Now maki asks once per project root, with Trust, Not now and Never as the options, and Not now is preselected so Enter and Escape are both safe.

## Installation paths and release momentum

Installation is a shell script, and the README tells you to read it before running it, which is the correct instruction for any curl-and-pipe install.

```sh
curl -fsSL https://maki.sh/install.sh -o install.sh
cat install.sh
chmod +x install.sh && sh install.sh
```

The one-liner `curl -fsSL https://maki.sh/install.sh | sh` also exists. On Linux and macOS it installs to `~/.local/bin`, overridable with `MAKI_INSTALL_DIR`. Windows has PowerShell and Git Bash paths, and both land in `%LOCALAPPDATA%\maki` on the user PATH.

There are two paths that avoid the install script entirely, both useful on a machine you would rather not hand a shell script to. Nix runs the project directly from GitHub with `nix run github:tontinton/maki`, and Cargo builds from the main branch with `--locked --git`. Pre-built binaries are also published on the releases page.

For migrating from another agent, `--print --output-format stream-json` runs maki with no UI, and the output is compatible with Claude Code. For editor integration, `maki acp` speaks the Agent Client Protocol, so a Zed `settings.json` entry pointing `command` at `maki` with the `acp` argument is enough to wire it up.

On release pace: version 0.5.3 landed 2026-09-10, 0.5.4 on 2026-09-15, and 0.5.5 on 2026-09-16, with the last push on 2026-09-19. Those notes read like an author reacting to his own users. Version 0.5.5 made Escape cancel a compaction, because 0.5.4 began honouring a server `Retry-After` header that could park a request for an hour, and it also fixed key rotation in a comma-separated `ANTHROPIC_API_KEY` so a 429 no longer wastes a key on backoff.

## Conclusion

maki is distinctive for treating the context window as something you budget rather than something you fill. Its two tools that move information out of the conversation, the `index` skeleton and the `code_execution` interpreter, are the parts worth understanding before anything else, and the README's own arithmetic on what each saves is the most credible part of the documentation. The install story is short and the provider list is long enough that you will find your existing key in it. Read the permission parsing section before your first unattended run, because a coding agent that understands `git diff && rm -rf /` well enough to split it into two permission checks is also one you want configured deliberately. Start with `--print --output-format stream-json` if you are migrating from another agent, since the output is designed to be compatible.

## FAQ

### What language is maki written in?

Rust, with a terminal UI built on ratatui and no JavaScript. Plugins and configuration are Lua, following a Neovim-style model, and the agent can also run shell commands you invoke yourself with `!` or `!!`.

### How do I install maki?

Download `install.sh` from maki.sh and read it before running it, or use the one-liner. It installs to `~/.local/bin`, overridable with `MAKI_INSTALL_DIR`. There is also a Nix path, a Cargo path, and a Windows PowerShell script.

### Which model providers does maki support?

About eighteen, including Anthropic, OpenAI, xAI, Google, Copilot, Ollama, llama.cpp, Mistral, Z.AI, DeepSeek, OpenRouter, Requesty, Regolo, OpenRouter and Aperture. Anthropic accepts an API key only, since the README states OAuth use is against its terms of service.

### What does maki's index tool actually do?

It uses tree-sitter to parse supported languages into a high-level skeleton with exact line ranges for each item, so the agent can decide whether to read a region without loading a whole file. The README's own measurement is 59 tokens per turn added and 224 saved on reads.

### Can maki run inside an editor instead of the terminal?

Yes. `maki acp` speaks the Agent Client Protocol, so an editor such as Zed can launch it as a custom agent server. There is also a headless mode, `--print --output-format stream-json`, whose output is compatible with Claude Code.

## Sources

- [License: MIT](https://github.com/tontinton/maki/blob/main/LICENSE)
- [Project website](https://maki.sh)
- [README](https://github.com/tontinton/maki/blob/main/README.md)
- [Releases](https://github.com/tontinton/maki/releases)
- [tontinton/maki on GitHub](https://github.com/tontinton/maki)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tontinton-maki