How to Use Maki? The Beginner's Guide to the Rust Coding Agent That Sips Context Tokens

CodexFuse Team · 2026-11-05T07:38:17.918Z · 17 min read min read

How to Use Maki?

Learning how to use Maki starts with a single idea: this is a coding agent that treats your context window like a budget, not a bin. Maki is a Rust terminal coding agent that runs in your terminal, takes plain-English instructions, and edits your code, while spending as few context tokens as possible on the work. You install it, point it at a model with an API key, and type what you want changed, and the agent reads, edits, and runs commands for you.

The short version is five steps: install the binary, set one API key, open your project folder, type a task, and watch the token and cost counters in the status bar. The rest of this guide walks through each step, explains the token-saving tools that make Maki different, and shows how its Lua plugins and permission system work. Before you run any agent against a real project, it is worth checking the values you will hash or sign in your integrations with a SHA-256 hash generator, and worth knowing that the servers behind an agent setup like this usually run on VPS hosting.

What Is Maki?

The Maki Rust coding agent is built to minimize context-token spend. It is a standalone terminal user interface (TUI) agent written in Rust with the ratatui library, and the Maki tontinton repository is public under the MIT license. The project appeared on Show HN on November 4, 2026, one day before this guide was written, so the features and version numbers here describe Maki as of November 5, 2026, and a fast-moving project can change them quickly.

Unlike a plugin that sits on top of another agent, Maki replaces the agent entirely: it has its own interface, its own tools, and its own way of managing context. The author describes it as an efficient AI coding agent extendable by Neovim-like Lua plugins, and that sentence is the whole design in miniature: speed and low token use on the outside, a hackable plugin system on the inside.

The project is young but active. Its repository was created on February 13, 2026, and by November 5 it had 2,481 commits, 1,370 stars, 216 forks, and 79 releases. That is about 9 commits a day on average across roughly 265 days, which is the shape of a project under daily development rather than a weekend experiment.

How Do You Install Maki?

Installing Maki takes one command on each platform, and the binary lands in a folder already on your path or one you can add. The installer scripts come from the project's own site, and the project itself advises reading a script before running it rather than piping it straight into a shell.

Getting Maki running takes five steps:

1. Download the installer for your system: on Linux or macOS, fetch install.sh from maki.sh; on Windows, fetch install.ps1.
2. Read the script, then run it. It installs to ~/.local/bin on Linux and macOS, and to %LOCALAPPDATA%\maki on Windows.
3. Or use a package manager instead: Homebrew users run brew install maki, and Nix users run nix run github:tontinton/maki.
4. Set one API key for the provider you want, for example ANTHROPIC_API_KEY for Anthropic.
5. Type maki in your project folder and give it a task.

If you want the newest code instead of the newest release, the from-source install with cargo is the documented path, and pre-built binaries are also available from the project's GitHub Releases page. Either way, verify the binary runs with maki --version before you point it at a real project.

How Do You Start Your First Session?

Maki starts from your terminal, inside the project you want it to work on. Type maki in the project folder and the TUI opens at 60 frames per second, with the token count, cost, and model always visible in the status bar. Nothing is hidden: the philosophy is that you should always see what the agent is spending.

The first thing Maki needs is a model, and that means one API key. The provider list is long: Anthropic, OpenAI, xAI, Google, Copilot, Ollama, llama.cpp, Mistral, Z.AI, DeepSeek, OpenRouter, Requesty, Synthetic, Regolo, TensorX, OpenCode Zen, OpenCode Go, and Aperture.

Once the key is set, the session is a conversation. Type a task in plain English, and Maki plans, reads, edits, and runs commands. You can flip between parallel sessions and subagent chats with /tasks (Ctrl-X), search the conversation with Ctrl-F, and run a side question that does not disturb the current session with /btw.

Two details matter on day one. First, Maki keeps its system prompt and tool definitions short on purpose, and it builds them once per session so providers can cache by prefix; editing near the front of the prompt can make the next request pay for the whole conversation again. Second, sessions can be resumed, so a long job does not have to finish in one sitting.

How Does Maki Save Context Tokens?

Maki context tokens are the whole reason the tool exists, and the savings come from five mechanisms that attack the biggest costs first. File reads are about 65% of the tokens in a typical session, according to the project's own measurements, and bash output is about 12%, so the tools that shrink reads matter far more than the ones that shrink shell output.

The arithmetic is straightforward, and the project publishes it as its own measurements. The index tool costs 59 tokens per turn and saves 224 on reads, a net saving of 165 tokens per turn. Over 100 turns that is 16,500 tokens kept out of the context window, and over 1,000 turns it is 165,000.

The split also tells you where not to look for savings. Maki can use the rtk tool to compress bash output by about half, but bash is only 12% of total token use, so that saves roughly 6% overall. Reads at 65% plus bash at 12% account for 77% of a session's tokens, which is why the index tool, not the shell filter, is the headline feature.

How Does the index Tool Work?

The index tool is Maki's signature move, and it works by reading less. Instead of handing the model a whole file, index parses the file with tree-sitter and returns a compact skeleton: imports, type definitions, and function signatures with their exact line ranges.

The model sees the structure first, then reads only the lines it needs. The project's own example is a small Rust file: the full file costs 164 tokens, and the skeleton costs 94, which is 43% smaller. Seventy tokens saved on one read does not sound dramatic, but reads are 65% of a session, so the savings compound on every file the agent touches.

The tool covers 15 languages, and the project encourages using it before reads as a habit. A skeleton that says count_words lives on lines 11 to 13 is enough for the model to decide whether that function matters, and it never pays to read the other lines at all.

How Does code_execution Keep Data Out of Context?

The code_execution tool is the second big saver, and it works by thinking inside a sandbox. It runs an embedded Python interpreter, called monty, in which every Maki tool is available as an async function, so the model can write a script, run it, and see only what the script prints.

The project's example is finding dead exports in a TypeScript repository. The model gathers every source file, reads them inside the sandbox, compares exports against imports, and prints three lines naming the unused exports. About 40,000 tokens of file reads become about 30 tokens of output, a reduction the project describes as roughly 1,300 times; the raw division, 40,000 divided by 30, is about 1,333.

The sandbox is limited by time and memory, and the pattern generalizes: whenever a job needs a count, a filter, or an aggregation, the model runs code and reads the answer instead of reading the data. Sandboxed execution is a pattern other agent platforms use too, and a separate guide explains how to use E2B for hosted agent sandboxes with their own trade-offs.

How Do Subagents and Model Tiers Work?

Maki delegates work to subagents through the task tool, and it picks a model tier for each one. The model chooses weak, medium, or strong for the subagent, roughly Haiku-tier for grep-heavy research and Opus-tier for architecture, and you get a summary back instead of the full transcript.

That choice is a cost control as much as a quality control. A research subagent does not need the strongest model to grep a codebase, and a summary keeps the parent session's context small. Each subagent gets its own chat window, and /tasks (Ctrl-X) flips between them so you can watch a long job without losing your place.

Long sessions get compacted automatically: images and thinking blocks go first, then old turns are summarized. The memory tool adds a longer horizon, keeping facts across sessions when you tell Maki to remember something, and /memory lets you view, edit, or delete what it stored.

How Do Permissions Work in Maki?

Maki's permission system is built on a simple observation: most agents do not really know what a shell command does. When an agent runs git diff && rm -rf /, a typical agent sees git and approves it, while Maki parses the command with tree-sitter and correctly flags both git and rm.

The parser understands subshells, command substitution, and pipes, so a dangerous command hiding behind a harmless first word still gets caught. Each tool has its own allow and deny rules, and --yolo skips the checks entirely when you are working in a throwaway environment and accept the risk.

The same care shows up in the webfetch tool, which carries SSRF protection. The shell shortcuts are just as deliberate: a single bang runs a shell command, and a double bang runs it silently so Maki never sees the output.

Double-Escape rewinds the chat history when a session goes off track, though it rewinds only the conversation, not the code.

How Do You Extend Maki with Lua Plugins?

Maki Lua plugins are the reason the agent can grow without growing its core. Every built-in tool, including read, bash, edit, and batch, is itself a Lua plugin, and the plugin API mirrors Neovim, with maki.fs, maki.uv, maki.keymap, and maki.treesitter among the modules it exposes.

Adding a plugin means dropping a file in ~/.config/maki/lua/ and requiring it from init.lua. From there a plugin can add tools, providers, slash commands, keymaps, and UI, and anything Maki does out of the box, a plugin can do too. The project ships an example config repository, tontinton/makiconf, that includes a semantic code-search tool and an ast-grep MCP server.

The project's own examples show the shape of it. One registers a ci_status tool that fetches the latest CI run for the current branch and shows it in a buffer, so the model can check CI itself instead of asking you.

Another registers a /standup command that shows yesterday's commits in a floating window. Both are a few dozen lines of Lua, and both teach the agent a skill it did not have.

Plugins can even replace a named section of the system prompt, or the whole template, with maki.api.set_prompt. The sections you can override are identity, tone, objectivity, tool_usage, efficient_tools, conventions, completion, and after_instructions, and Maki keeps its coding defaults wherever no plugin replaces them.

Maki vs Claude Code: What Is Different?

Maki vs Claude Code is the comparison most new users make first, because the two tools do the same job with opposite priorities. Claude Code is the established, polished agent with deep ecosystem support, and Maki is the leaner Rust alternative that trades some of that polish for speed and token discipline.

The headless compatibility is the practical bridge between them. Maki's --print --output-format stream-json output is compatible with Claude Code, so existing scripts and harnesses built around Claude Code's JSON output can run against Maki without being rewritten. That compatibility is vendor-claimed, so test it against your own harness before relying on it, and a separate guide explains how to use Claude Code if you want the comparison from the other side.

The benchmark the project publishes tells the same story in numbers. On the FrontierHarness Eval, Maki 0.5.5 scored a 70% pass rate at $2.06 per pass, against Codex at 66.7% and $3.47 and Claude Code at 63.3% and $18.34.

Claude Code costs about 8.9 times more per pass than Maki, $18.34 divided by $2.06, while scoring 6.7 points lower, and Codex costs about 1.7 times more per pass. Benchmarks are vendor-selected, so treat them as one data point, not a verdict.

The comparison members around Maki are OpenCode, pi, and the Codex CLI, which sit in the same lane as terminal-first agents, and a separate guide explains how to use OpenCode for the same kind of terminal-first workflow.

Who Should Use Maki, and Who Should Not?

Maki fits developers who pay for their own context tokens and feel the bill. If you run long agent sessions, work in large codebases, or use API pricing where every token is metered, the index tool and tiered subagents attack the exact costs you already pay.

It also fits Neovim users, because the Lua plugin API feels like home, and Rust developers, because the whole agent is a native binary they can read and build. The Maki coding agent rewards the kind of user who reads a status bar and asks what each number costs.

It fits less well if you need a mature ecosystem today. Maki is at version 0.5.5, its Show HN debut was November 4, 2026, and its documentation and plugin catalog are young. Teams that need enterprise support, deep IDE integration, or a large community answering questions will find Claude Code or OpenCode more settled for now.

The honest way to decide is to run it on a real task and read the status bar. The token count, cost, and model are always visible, so a single afternoon of real work tells you more than any benchmark. If the numbers come back lower than your current agent for the same result, Maki has earned its place; if they do not, you have lost an hour and learned something concrete.

One more fact belongs in the decision, because it cuts both ways: the project's own disclaimer says more than 90% of Maki's code was written by Maki itself, guided by humans. That is a strong dogfooding signal for a coding agent, and it is also a reminder that the codebase is young and shaped by the tool it describes.

Sources

Maki homepage (maki.sh) — the vendor's own overview of the index, code_execution, tool_search, task, and compaction tools, the Lua plugin system, the FrontierHarness Eval benchmark for version 0.5.5, and the permission model; fetched November 5, 2026.

Maki repository README (github.com/tontinton/maki) — installation commands for Linux, macOS, Windows, Homebrew, cargo, and Nix; the full provider list and API-key setup; the ACP configuration example; repository statistics (1,370 stars, 216 forks, 2,481 commits, 79 releases, MIT license, created February 13, 2026); fetched November 5, 2026.

Context — Maki Docs (maki.sh/docs/context) — how the system prompt is built once per session, how instruction files (AGENTS.md through CODING_AGENT.md) and AGENTS.local.md load, the @ file-mention picker, and the 100-image limit; fetched November 5, 2026.

Claude Code Tools: RTK, ccusage & GUIs (cc.bruniaux.com) — an independent catalog that lists Maki as a standalone Rust TUI agent that replaces Claude Code rather than extending it, with the index-tool token measurements; fetched November 5, 2026.

FrontierHarness Eval (frontierharness.org, via the benchmark chart on maki.sh) — Maki 0.5.5 at a 70% pass rate and $2.06 per pass against Codex (66.7%, $3.47) and Claude Code (63.3%, $18.34); fetched November 5, 2026.

Frequently Asked Questions

Is Maki free to use?

Yes. Maki is open source under the MIT license, and the binary itself costs nothing. You pay only for the model you point it at, through your own API key, so the cost of a session is the cost of the tokens the model consumes.

How much does Maki actually save on context tokens?

The vendor's own measurements say the index tool costs 59 tokens per turn and saves 224 on reads, a net saving of 165 tokens per turn. The headline examples are a file read cut from 164 tokens to 94, and a code-execution task that turns about 40,000 tokens of reads into about 30 tokens of output. Your mileage depends on your codebase and your habits, and the status bar shows the real numbers for every session.

Which models can Maki use?

Eighteen providers are built in, including Anthropic, OpenAI, Google, xAI, DeepSeek, Mistral, OpenRouter, Copilot, and local options such as Ollama and llama.cpp. A Lua plugin can register more providers, and each one behaves like a built-in provider once registered.

Can Maki replace Claude Code?

It can, for terminal-first workflows. Maki is a standalone agent with its own interface, and its headless --print --output-format stream-json output is compatible with Claude Code, so scripts built around Claude Code's JSON output can run against Maki. The trade is maturity: Claude Code has the larger ecosystem, while Maki is leaner and cheaper on tokens.

Is Maki safe to run on a real project?

Maki parses bash commands with tree-sitter before running them, so a chained command such as git diff && rm -rf / is flagged for both git and rm, and per-tool allow and deny rules let you control what it may do. That is a real safeguard, but no agent is a substitute for version control and backups, and --yolo turns the checks off entirely, so use it only in throwaway environments.