A fast, model-adaptive, terminal-native AI coding agent. You bring your own key; it does the work.
Apache 2.0 • Stars • X (Twitter)
Mindweave is a coding agent that lives in your terminal and works directly inside your repository, reading, searching, editing, running commands, and verifying its own work. It runs entirely on your machine: your code and your API key never touch a MindWeave server.
It's built lean on purpose. Instead of burning your context budget on heavy scaffolding, MindWeave keeps prompts thin and leaves the model room to actually reason about your code.
This section is permanent. It is the clearest statement of how this project is run, and it is here so nobody has to guess before they open an issue or write a line of code.
Mindweave is open to everyone for suggestions. The core is not open to everything.
Anyone can propose anything. Issues, discussions, pull requests, all welcome, and a good idea from a first-time contributor carries exactly as much weight as one from a maintainer. What differs is where the idea lands, because this project has two very different bars.
Drivers are wide open. Everything that makes one model family run at its best belongs in /drivers/<provider>: wire format, request shape, cache breakpoints, prices, context windows, parsing repairs. Models ship faster than anything else in this field, and the driver layer is designed to absorb that churn without the middle of the agent moving at all. If you want to change something, this is almost always where it should go, and the answer here is usually yes.
The core is deliberately near-finished, and the bar to change it is high on purpose. The agent loop, the tools, their safety gates, the system prompt, memory, and compaction are the parts every provider and every user depends on. They change when there is a reproduced bug, a demonstrated correctness gap, or a genuinely better architecture that has been measured against the current one. They do not change because something is fashionable, because another tool shipped it, or because it might be useful to somebody.
This is the same shape that has kept other long-lived systems alive. The Linux kernel holds a hard line against breaking userspace, and has for decades, while drivers underneath churn constantly. The stability is not stagnation. It is what makes everything built on top of it safe to rely on. A tool that rewrites its foundations every time the field moves is a tool nobody can build a habit around.
One test, and it is not about whether an idea is clever:
Does this make the developer spend less, get better results, and work faster and more smoothly?
If it does not clearly do at least one of those, with the others not made worse, the answer is no. That is not a lack of ambition. Every capability in the core is paid for by every user on every turn, forever, and most of the cost is invisible at the moment it is added.
We are looking to replace, not to accumulate. Every tool has a real price: its description and schema are sent to the model on every uncached turn, so a tool nobody uses still costs tokens on every request from everyone. It also costs something worse than tokens. A model choosing among a large set of tools chooses worse than one choosing among a small set, whatever the context window allows, so each addition slightly degrades every decision the agent makes about the tools that were already there.
So the preferred shape of a good contribution is: this replaces that, and here is why the result is smaller, faster, or more correct. A proposal that adds a capability and removes nothing has to justify its permanent cost to everyone, not just its benefit to the person proposing it.
Bring evidence, not preference. A better architecture is genuinely welcome and will be taken seriously, on these terms:
- Show what is slow, wrong, or clumsy about the current design, with something reproducible.
- Show that the alternative is actually better, measured against what exists now rather than against an idea of it.
- Show what it costs: tokens, complexity, surface area, and what it means for every provider rather than the one you use.
If the numbers say the current architecture is worse, it changes. That has already happened more than once in this project, and each time it was because someone measured rather than argued. What will not move it is "most tools do it this way" or "it would be nice to have".
Open a Discussion before writing code for anything core-shaped. We will talk it through, and where it makes sense we will test it properly and let the result decide. Being told no early is a better outcome than spending an afternoon on something that was never going to be merged, and this is written down precisely so that conversation can start honestly.
Start a dev server and the agent now tells you when it is actually up, stays quiet when you close it yourself, and still knows it is stopped if you ask later. All of it came from watching it get this wrong.
You are told when the app is up, not just when it was launched. Starting something long-running only ever produced one event: the moment it ended. So for a server, which is not supposed to end, there was nothing to report, and the agent would say it would let you know and then never could. A background process that is still alive after its startup window has come up, and that is now its own event. The agent says it is starting, then tells you when it is running.
Close your app and the agent says nothing. It also does not reopen it. That was already the intent, but the rule behind it read the exit code, and exit codes cannot tell these cases apart: on Windows a closed app and a port conflict both report 1, and anything stopped by a signal reports nothing at all. The question is now whether the thing ever came up. If you saw it running, you closing it is your business. If it never came up, you could not have known it failed, so you get told, with the error output.
It still knows what happened, even when it stays quiet. Stops that were not worth interrupting for used to be discarded outright, so the agent could not say your app had stopped, and had no answer if you asked why it was down. Every ending is now recorded; only the decision to interrupt you is conditional. Ask whether your app is running and you get a real answer, including whether you stopped it or it stopped itself.
You can say what you want to hear about. A command sent to the background takes a notify setting: tell me when it finishes, tell me only if it fails to start, or say nothing at all. Before this, the kind of thing being run was guessed from the command name, which meant cargo run, docker compose up, flask run and a plain path to a binary were all mistaken for short tasks. The guess remains as a default; it is no longer the decision.
Starting a second copy of something already running is refused. That check used to apply only to commands whose names looked like dev servers, so most things could quietly be launched twice and collide.
Next up: more of the same. The core is being gone through subsystem by subsystem, looking for the things that only show up when you actually run it.
UI: Is being designed and close to being finished.
- Fully local & BYOK. Bring your own model API key. No backend, no telemetry, no lock-in.
- Model-adaptive drivers. Each model family gets its own driver so it runs at its best without bloating the core. Only the driver you're using is ever loaded.
- Deterministic code intelligence. A background lane indexes your repo with tree-sitter and language servers (no tokens, no cost) so the agent understands your codebase, not just the open file.
- Real tools. File read/edit, multi-file edits, ripgrep search, shell with background jobs, sub-agents, and diagnostics, with read-before-edit safety and an undo net.
- Session memory. Long sessions stay sharp: automatic compaction plus a continuously-maintained state summary that survives it. The agent can also read its own earlier sessions in a project, so "what did we do last time" gets a real answer.
- MCP servers. Connect external tool servers (GitHub, Postgres, your own) with
/mcp addor just by asking. They start with your session, and their tools are treated as untrusted by default. - Per-project governor. Give a project standing rules, reusable skills, and forbidden paths/commands that the agent must respect.
- Interaction modes. Lightning (auto), Architect (plan-only, read-only), cycled with
shift-tab.
- Node.js 20+
- A model API key (see below)
- Optional: ripgrep (
rg) for faster search. MindWeave falls back to a built-in walker if it's not installed.
Platforms: MindWeave is developed and tested primarily on Windows. It's built on cross-platform Node and should run on macOS and Linux. If you hit a platform issue there, please open an issue.
Mindweave installs from source:
git clone https://github.com/mindweave-cli/Mindweave
cd Mindweave
npm install
npm run build
npm link # makes the `mindweave` command available globallycd your-project
mindweaveOn first launch, MindWeave asks for your API key and saves it to ~/.mindweave/.env so it works in every project. Then just type what you want done.
Mindweave is bring-your-own-key. Two providers ship today:
DEEPSEEK_API_KEY=your-key-here # deepseek-v4-flash, deepseek-v4-pro
ANTHROPIC_API_KEY=your-key-here # claude-sonnet-5, claude-opus-5
You only need the key for the provider whose models you use. Set both and you can switch between them with /model in the same project. Set a key during the first-run prompt, in ~/.mindweave/.env, or as an environment variable.
/modelpicks which model answers./thinkpicks how hard it reasons.
Your choice is remembered per project. See src/drivers/PROVIDERS.md for the current model list, and src/drivers/README.md if you want to build a driver for another model.
MCP servers give the agent tools MindWeave doesn't ship: issue trackers, databases, cloud APIs, internal services. Add one and it's available from that moment on, in every future session, with nothing to start by hand.
# a local server
/mcp add github npx -y @modelcontextprotocol/server-github --env GITHUB_TOKEN=ghp_x
# a remote one
/mcp add --http internal https://tools.acme.dev/mcp --header 'Authorization: Bearer t'
# available in every project, not just this one
/mcp add --global notes npx -y some-notes-server
# a server with its own flags: everything after -- goes to the server
/mcp add mine my-server -- --port 9000 --verbose
/mcp # what's running, and reconnect anything that isn't
/mcp remove x # stop configuring itYou can also just ask: "add the github mcp server, my token's in GITHUB_TOKEN." The agent writes the config and asks you to confirm before anything is saved.
Servers are declared in .mindweave/mcp.json (this project) or ~/.mindweave/mcp.json (everywhere), in the same format every other MCP client uses, so an existing config can be pasted straight in.
Two things worth knowing. If a server's tool description changes between sessions, that tool is blocked until you approve it, because a changed description is the main way a trusted server turns hostile. And remote servers requiring OAuth aren't supported yet; they'll show as needs-auth.
- v1.0: first public release
- v1.1: Anthropic (Claude) driver, providers loaded on demand, provider-aware setup, cut off replies caught
- v1.1.2: shared core made provider-neutral, with tests guarding it
- v1.2: reads its own past sessions, failure loops interrupt instead of stopping dead, every early stop explains itself
- v1.3: MCP / external tool servers, with rug-pull protection and a deferred tool pool
- v1.4: MCP hardening with resources and server prompts, and rebuilt editing tools
- v1.5: processes cleaned up properly, an Esc that actually cancels, per-model compaction
- v1.6: background apps report when they are up, and stay quiet when you close them
- Core hardening, the current focus: every subsystem the agent actually runs, gone through one at a time
- More model drivers (OpenAI, Qwen, Ollama, …), community-built
- Verified macOS / Linux support
- OAuth for remote MCP servers, once the core is where it needs to be
Please open an issue. Mindweave is developed by running it on real projects and fixing what breaks, so a reproduction from someone else's setup is genuinely the most useful thing you can send. Nearly every item in the release notes above started as a failure someone watched happen.
Useful to include: your OS and terminal, which model you were on, and the steps that led to it. If the agent did something odd rather than crashed, the transcript around it helps more than a description does.
Especially worth reporting:
- Anything MCP. It's still young, and only one real published server has been driven end to end; resources and prompts have only been tested against servers we wrote. Real servers will find edges we didn't.
- A tool the agent was offered but couldn't call, or one it insisted didn't exist.
- Anything on macOS or Linux. Development happens on Windows; those two are believed to work but aren't verified.
- A prompt or menu that says something untrue. Those can't crash and don't fail tests, so they survive until a person notices.
MindWeave is open source and contributions are welcome, especially model drivers. See the Contributing Guide, and open an issue or a Discussion to claim a provider.
Small fixes and reproduced bugs with a failing test can go straight to a pull request. For anything larger, start a Discussion first. The philosophy section above explains where the two bars sit and what evidence moves the core one, and the guide covers the mechanics.