Start with Mavambo

Install and open a project

About 2 minutes

Download the installer and run it, the same as any other Windows application. Mavambo brings everything it needs with it — there is nothing to install beforehand and nothing else on your computer is changed.

When it opens for the first time it asks you to choose a folder to work in. Pick a project you know well. Mavambo reads the files inside that folder and nothing outside it.

You should now see the workspace, with your project name in the header and an empty conversation.

Your first task

About 3 minutes

There is a box at the bottom of the window. Type what you want in ordinary English — you are talking to it, not typing commands.

Start with a question

The best first task is one that only reads. You get an answer straight away and nothing on your computer changes:

Mavambo opens the files it needs and answers in plain language. You will see it working as it goes — which files it looked at, and what it concluded. Nothing is hidden.

Then ask for a change

Now something that actually edits a file. Describe the result you want, not the steps to get there:

This time Mavambo shows you the change first — the old text and the new text, side by side — and waits. Nothing is written until you approve it. If the change is not what you meant, reject it and say what you actually wanted.

You should now see an answer in the conversation, and — after approving the second request — a corrected file in your project.

Why it asked permission

About 4 minutes — the most important page here

Mavambo asks before it runs a command, before it writes a file, and before it runs any tool you have added. Every time, one approval per action. This is the single behaviour that most distinguishes it, so it is worth understanding rather than clicking past.

Nothing happens behind your back. If you did not approve it, it did not happen.

Adding something is not the same as running it

When you add a tool, Mavambo downloads it, reads it, checks it, and files it away. It does not run it. No setup script executes, nothing is fetched from anywhere else. That is what makes adding a tool a safe thing to do while you are still deciding whether you trust it.

If a tool needs extra software packages to work, you are asked about that separately — because unlike copying files, installing packages does run code. Two different questions, asked at two different moments, deliberately.

What the dialog tells you

Before a tool is added you see everything it has declared about itself:

Two extra lines appear when they apply, and they are the two worth pausing on. Network means the tool reaches the internet. Reads lists, by name, the settings from your computer it will be handed — and when that line is present, the reassurance above narrows to match it. No tool may ever ask for Mavambo's own API key; those names are refused outright.

You should now be able to read any of these dialogs and say what the tool can and cannot get to.

Sessions

About 2 minutes

A session is one continuous conversation about one project. They are listed down the side of the window, you can rename them, and opening one puts you back exactly where you left off.

Start a new session whenever you move to an unrelated task. It keeps each conversation focused, makes them easier to find later, and — as the next page explains — costs you less.

What carries over between sessions: your files and your project, obviously. What does not: the conversation itself, and everything Mavambo had worked out about what you were doing.

Answering from your phone

About 2 minutes

Mavambo can reach you on WhatsApp. When a turn stops on a proposal and you are not at the machine, the approval arrives in your own Message yourself chat, and replying 1 unblocks it. What the session says next comes back to the same chat, and what you type there goes to the session.

Linking a phone

Open Settings › WhatsApp and press Link a phone. A code appears in the panel. On your phone, open WhatsApp › Settings › Linked devices › Link a device and scan it. The panel says when it is linked.

This is a one-off. The link is remembered, so opening Mavambo tomorrow does not ask you to scan anything again. There is nothing extra to install and no terminal involved.

What you type

One rule: commands start with two dashes. Anything without them is just a message, and goes to Mavambo as an instruction. That is the whole of it — you can hold a normal conversation without ever tripping a command by accident.

When it is waiting on you

A list on screen outranks a waiting proposal, because 1 means both “the first row” and “approve”. Opening a session re-reads it and announces the proposal again, so nothing is lost by choosing first.

Starting one from scratch

Nothing needs to be open on the computer first. Send --new and the chat offers you somewhere to put it.

You get a numbered list of places to start. A › at the end of a row means there are folders inside it, and a row marked (a project you've used) is somewhere you have worked before. Reply with a number to go in.

Three commands move you around from there: --up goes back out one level, --more shows the next nine, and --new word narrows a long list to the rows matching that word.

When you are standing in the folder you want, --here starts the session:

To work somewhere that does not exist yet, --create makes the folder and starts a session inside it in one step — there is no need to create it and then go in:

Either way the chat confirms with the session name and the full path it landed in, then says what it is doing. The phone is attached to that new session immediately, so the next thing you type becomes its first instruction.

Choosing which session

When the phone connects it offers your sessions as a numbered list, and you reply with a number to open one. Each row carries a badge for what that session is doing — working, or waiting on you — which is what makes the menu worth opening even when you already know which session you want. Send --list at any time to see it again.

Only sessions that have a folder are listed. A session that was never pointed at one cannot be worked on from a phone, and pointing it at a folder is something you do in the app.

If a different session stops and needs you, that arrives as its own message telling you to send --list to switch. It deliberately has nothing to answer with 1, so a reflexive reply cannot approve the wrong project's command.

Keys and cost

About 2 minutes

Mavambo needs an API key from an AI provider to think. You paste it into Settings once. It is kept on your own computer, and it is never given to a tool — no tool can ask for it.

Every request costs a small amount, billed by that provider rather than by Mavambo. The usage dashboard shows what each session has spent, and the small meter in the header is the same figure at a glance. Watch it for a day and you will quickly get a feel for which kinds of request are expensive.

Models and providers

About 3 minutes

Mavambo does not ship a model. It talks to one you pay for, using your own key. Two providers are supported in v1.0: DeepSeek and OpenAI.

There is no fixed list of models. When you open Settings › API Key, Mavambo asks the provider which models your key can reach and offers those. A model released after this page was written will simply appear in the menu — you do not need a new version of Mavambo to use it.

DeepSeek

Reaches https://api.deepseek.com. Any model your key can reach is offered; deepseek-chat is the usual starting point.

• The effort control applies to every DeepSeek model.
• Its ladder is low, high, max — not the low/medium/high most APIs use. DeepSeek accepts medium and xhigh but maps them onto high, so offering them would put two entries in the menu that do the same thing.
• Effort defaults to low. DeepSeek's own default is high, but raising it multiplies what you spend, so Mavambo leaves that as your decision — one click in the composer.
• DeepSeek publishes a balance endpoint, so the meter in the header can show what is left against what you topped up.

OpenAI

Reaches https://api.openai.com/v1. Any model your key can reach is offered; gpt-4o-mini is a cheap place to start.

• The effort control is sent only to the reasoning families that document it — o1, o3, o4 and gpt-5. On any other OpenAI model the parameter is rejected outright, so Mavambo omits it and the control has no effect.
• Its ladder is low, medium, high, defaulting to medium. Some models also accept minimal, none or xhigh, but which ones varies — a menu entry that fails on the model you happen to be using is worse than a shorter menu.
• OpenAI publishes no balance endpoint, so there is no top-up meter on this card. Per-session token counts and costs are still tracked in Usage.

Adding skills and tools

About 3 minutes

Mavambo can be taught new things. There are two kinds, and the difference is simple:

• A skill is instructions — it teaches Mavambo a procedure, a house style, a checklist. It is just writing. Nothing runs.
• A tool is a small program that lets Mavambo do something it otherwise cannot: read a PDF, pull text out of an image, talk to a service.

Adding one

Open Settings, choose Skills or Tools, and paste in the address of the repository that holds it. For example:

You will get the dialog from the previous page — read it, then confirm. Now start a new session, because the tool list is fixed when a session begins.

Ask for something the new tool covers, and Mavambo will offer to use it:

Next: once you have used someone else's tool, the natural next thought is wanting one of your own. That is track two — the only part of Mavambo where you run a command yourself, and even then just one: the checker that confirms a tool is correct before you publish it.

Skill or tool?

About 2 minutes — decide this first

Two extension types, and people reach for the wrong one constantly. The rule of thumb: if you are about to write code that only rearranges words, you wanted a skill.

Quickstart: your first tool

About 12 minutes — build first, understand after

You are going to build a word counter. It is deliberately trivial: the point is to see the whole loop — write, check, install, get called — before any of the reference material matters.

{
  "name": "word_count",
  "description": "Count words and lines in text files in the project. Use when the user asks how long a document is, or to compare the length of several files.",
  "entry": ["python", "handler.py"],
  "timeout_seconds": 30,
  "parameters": {
    "type": "object",
    "properties": {
      "paths": {
        "type": "array",
        "items": { "type": "string" },
        "minItems": 1,
        "description": "Project-relative file paths to count."
      }
    },
    "required": ["paths"],
    "additionalProperties": false
  }
}

import json, sys
from pathlib import Path

request = json.load(sys.stdin)
folder = Path(request["cwd"])

try:
    counts = []
    for name in request["arguments"]["paths"]:
        text = (folder / name).read_text(encoding="utf-8")
        counts.append({
            "path": name,
            "words": len(text.split()),
            "lines": text.count("\n") + 1,
        })
    print(json.dumps({"result": {"files": counts}}))
except Exception as error:
    # A failed tool call is a normal outcome, not a crash. Say what
    # went wrong so the model can choose a different next step.
    print(json.dumps({"error": str(error)}))

The stdio contract

About 4 minutes

Your handler is launched as a subprocess in the active project folder. It gets one JSON object on stdin:

{
  "tool": "word_count",
  "arguments": { "paths": ["README.md", "CONTRIBUTING.md"] },
  "cwd": "C:\\Users\\you\\projects\\thing"
}

It must print exactly one JSON object to stdout and exit 0. That object carries either result or error:

// success — anything JSON-serializable
{ "result": { "files": […] } }

// failure — a sentence the model can act on
{ "error": "README.md was not found in this project" }

stdout is the channel

Anything else you print corrupts the response. No progress lines, no print("starting…"), no stray library banner. If you want diagnostics, write to stderr — it is captured, bounded, and shown when something goes wrong.

Declaring parameters

About 5 minutes

parameters is a JSON Schema object and is required, even when your tool takes no arguments. It must be "type": "object", and you should always set "additionalProperties": false.

The validator implements eleven keywords

And here is the part that surprises people: a constraint keyword outside that set is refused, not ignored.

Types

Enforced types are object, array, string, integer, and boolean.

Size limits

At most 40 properties counted through nested objects and array items, and at most 5 levels deep. Both are measured against the widest and deepest built-in tools, so they bite third-party excess and not ordinary work.

Depth is the one to respect. A deeply nested argument cannot be composed from a signature line, which forces the model into an extra round trip before every single call — you pay for that nesting forever.

Write the description for a router, not a reader

Your description is how the model decides whether to reach for your tool at all. Say what it does and when to use it. Cap is 500 characters; a description longer than that is documentation, and documentation belongs in your README where nobody pays for it on every call.

Dependencies and capabilities

About 5 minutes

dependencies

A list of at most 20 requirements, each a package name with optional extras and version specifiers. Nothing else is accepted:

"dependencies": ["mss>=10", "pillow"]          // fine

// all refused:
"git+https://github.com/me/thing"       // a host nobody was shown
"./vendor/thing"                        // a path the tool chose
"--index-url=https://my.mirror"         // a flag, not a package
"requests; os_name=='nt'"               // machine-dependent

Every exclusion is a way to install code from somewhere the approval prompt did not name. The whole argument for a second prompt is that the user sees the packages before code from PyPI runs; a requirement that can point anywhere makes that dialog a decoration.

Dependencies are never installed silently. If a user declines, or copies your folder in by hand, the tool stays installed and does not load — and the reported reason names the fix:

That repair is command line only for now. The app lists the tool, but has no button that runs it.

network

A boolean, default false. Set it to true if your tool reaches the internet at any point, and be honest about indirect cases — a library that downloads a model on first use makes your tool a network tool, however offline it feels.

environment

An allowlist of up to 10 environment variable names your tool will be handed — each an ordinary variable name in capitals, digits and underscores. It receives those and nothing else. Names belonging to Mavambo itself are refused at load, so no tool can ask for the agent's API key.

timeout_seconds

Default 30. For a local tool the ceiling is 180, and anything above it is clamped down silently rather than refused. A tool that declares network is the exception — it keeps whatever timeout it sets, with no ceiling at all, because Mavambo cannot know how long a remote host will take to answer. Either way the value is shown in the install dialog, so an absurd one is visible at the moment trust is granted. If a local tool genuinely cannot finish inside 180 seconds, it needs to do less per call — or write its output to disk and return a path.

Writing a skill

About 4 minutes

A skill is one folder with a SKILL.md in it. The frontmatter takes six fields, of which two matter:

---
name: commit-style
description: Write commit messages in our house convention. Use when
  committing, amending, or rewriting history in this repository.
---

# Commit style

Subject line in the imperative, under 60 characters, no trailing period…

Skill names are lowercase and hyphenated — not the underscored style tools use. That is not an inconsistency: skills follow the Agent Skills specification, so a skill that passes here also loads in other harnesses. Tool names become internal action types and match the built-in tools instead.

The body is Markdown, capped at 60,000 characters. It flows straight into the model's context when the skill activates, so length has a real price. Anything long, optional, or reference-shaped belongs in a separate file the skill links to.

Publishing

About 4 minutes

Put the tool folder at the root of a public repository, or in a subdirectory of one — a repository can hold as many tools as you like, each in its own folder. That is how the reference tools are laid out.

Your users add it the same way you did in the quickstart: they paste the folder's address into Settings → Tools and confirm the dialog.

The install pins to the commit it resolved, and that commit is shown in the dialog. Users need git installed; nothing else.

Before you push

• Make the name specific. ocr_read, not read. The namespace is flat and collisions are refused outright.
• Run tools check from a clean clone, not from the folder you have been editing. It catches the file you forgot to commit.
• Read your own install dialog. Would you say yes to it from a stranger? If the description does not justify the capabilities, fix the description or drop a capability.
• Loosen your pins. See the shared environment note above.
• Write the README for an evaluator, not a user. The first question is not "how do I call this" — it is "what is this going to do on my machine".

tool.json fields

Any field not in this table is refused — an unrecognised key is more often a typo than an extension.

Schema keywords

Developer commands

Mavambo is a desktop application, so adding, removing, listing, enabling and disabling skills and tools all happen in Settings — there is nothing to type for any of that. Only two commands have no button, because both are for building a tool rather than using one. If you are not writing a tool, you never need either.

Both run from the Mavambo backend folder — the one holding main.py.

Error index

Paste the message you got into search, or find it here. Every entry is the literal text Mavambo prints.

Reference tools

Two published, working tools to read, clone, and copy from. Both live in one repository, each in its own folder — which is also the layout to copy if you plan to publish more than one thing.

They are a deliberate pair. Mavambo reads text, not pictures, so anything that arrives as an image or a page layout has to be turned into text before the agent can reason about it at all. Between them these two cover the cheap case and the expensive one.

Known limits

Written down rather than discovered. All three are things we intend to change.

• The tool namespace is flat. Names are global on a user's machine and collisions are refused outright. Until that changes, choosing a specific name is the whole defence — which is why these docs push it so hard.
• The dependency environment is shared. One virtual environment across every installed tool. Conflicts are detected and reported honestly, but a strict pin in one tool can block an install months later.
• There is no update command. Installs pin to a commit and nothing surfaces a newer one. Remove and reinstall is the current answer.