MANTRA

v0.7.0 · MIT · Linux & macOS · two Rust binaries

MANTRA

One terminal for coding agents — alone, or as a team.

Runs OpenAI Codex, Claude Code and its own small harness, Bija, mixed freely, on any model one of them can reach. Two Rust binaries, nothing written into your project — and, one flag away, an installable web UI and end-to-end encrypted remote access.

$ curl -fsSL https://raw.githubusercontent.com/sahelea1/mantra/master/install.sh | sh

Try it free in demo mode mantra --demo Read the docs →

◉ MANDALA

A team of agents, working as one.

Describe a goal. A planner shapes it, an orchestrator runs each phase, workers build in parallel in their own git worktrees, a gate merges, runs your checks and has a fresh read-only QA agent review the diff — fix workers repair what it finds — and a manager watches the whole run. Decisions travel up the chain — and reach you only when they have to.

mantra — mandala · {{ simTitle }}

        ✦ mantramandala› overview238615-build-a-todo-api-with-auth
        
        ⏱ {{ simElapsed }}Σ {{ simTokens }} tok● {{ activeCount }} active

        
          {{ ph.mark }}{{ ph.name }}

✦plannerastra·medium

{{ plannerCard.text }}

◉orchestratorastra·medium

{{ orchCard.text }}

◈managersol·medium

{{ mgrCard.text }}

{{ w.glyph }}{{ w.id }}{{ w.mark }}

{{ w.model }} {{ w.bar }}

{{ w.text }}

{{ emptyWorkersText }}

{{ gateGlyph }}{{ gateName }}{{ gateModel }}

{{ gateCard.text }}

pulse

            {{ e.time }}{{ e.g }}{{ e.t }}

          

        ←→ select1-9 jump⏎ zoomspace pauser retrym modelp pland diff
      

the mantra-default pattern · effort auto: Mantra picks it per spawn

sandbox {{ roleSel.sandbox }} · permission {{ roleSel.permission }}

CHAIN OF COMMAND

Ask up. Never guess. Reach you only when it matters.

Workers ask the orchestrator. The orchestrator asks the planner. The manager owns the run and unsticks whatever stalls. A watchdog nudges, respawns, escalates — and halts with a typed reason instead of looping. A question for you is a saffron band, not a stop: the run keeps going meanwhile.

☺you
credentials, the machine, a trade-off only you can make
✦ ◈planner · manager
revise the plan, hint, respawn, resume — or ask you
◉orchestrator
runs one phase: spawns, watches, corrects, waits
◆ ◇ ◎ ▲workers · gates · finale
own one task, one gate round, one finale step — workers in their own worktree

One agent, done properly.
Or a whole team.

You already have a coding agent in your terminal. Mantra is the room you put it in — and the room fits more than one. ctrl+o switches.

SOLO

Everything you actually want on screen

›The diff as it happens — +/- counts, inline hunks, ctrl+d for the full viewer
›Its plan, live — ticked as it goes
›A context gauge with the auto-compaction threshold marked
›Type while it works — queue a message, or ctrl+f it in right now
›Starts on Bija — sol-api, a key instead of a login — or any Codex or Claude Code model

MANDALA

A team that plans, builds and checks

›Phased plan you approve — validated before you see it, no overlapping scopes
›Workers build in parallel, each in its own git worktree with a declared file scope
›Gates merge and run your checks; a fresh read-only QA agent reviews the diff, fix workers repair what it finds
›Finale: one QA pass over the run’s diff → the planner’s verification. Then /land
›Work that splits wide: mantra --swarm 16 keeps sixteen small Bija workers busy at once

SWARMS · SHARED NOTES · YOUR TOOLS

Wider teams. Notes they share. Tools you give them.

Same room, more in it: a pattern cut for many small workers, an experimental notebook a group of agents writes together, any MCP server you already use, and a look at the screen for models that can see.

SWARM

Many small workers at once

$mantra --swarm 16 "port the tests to pytest"

The mantra-swarm pattern runs every role on Bija: the planner cuts the work into many small tasks with disjoint scopes — up to 32 a phase — and the orchestrator keeps N of them running. N is the run’s own, 1–128, never written into the saved pattern; /swarm N <goal> does it from inside the app, mantra run --parallel N for any pattern.

EXPERIMENTAL

Akasha: shared notes for agent groups

$mantra experimental enable akasha

Agents in a pattern’s group share one small block of notes — a fact about the code, a decision, an interface, a pitfall. Each keeps its own context; a note marked urgent reaches busy members mid-turn. Off until you switch it on, and its format and tools may still change. /akasha shows the blocks; mantra-swarm ships with one group, builders.

MCP

Your MCP servers, on all three backends

$mantra mcp add blender -- uvx blender-mcp

Any stdio MCP server — Blender, a browser, a database — handed to agents on Codex, Claude Code and Bija. Solo gets every enabled server by default; a Mandala role only what its pattern lists (mcp = ["blender"]). A call shows on the agent’s card as blender.get_scene_info.

VISION

Screenshots, when the model asks

◉mantra_screenshot · mantra_view_image

A model marked vision in /models gets two tools: a capture of the screen, or a region of it, saved under the run’s screenshots/; and a look at an image in its working directory. Nothing is ever captured unless the model calls the tool.

Swarms, Akasha, MCP and vision, in the docs →

Why you might want it

Parallelism that is actually safe

Every worker gets its own git worktree and a declared file scope. A plan whose parallel tasks overlap is rejected; a worker that edits outside its scope trips a wire.

Nothing silently stalls

A watchdog knows who should be busy and nudges, respawns or escalates when they are not. Failures halt with a reason and the key that fixes it, instead of looping.

It survives being closed

Runs are saved as they go. mantra runs resume <id> picks one up at the nearest safe boundary, from any directory. A run has one owner: a second Mantra won’t open it while the first still does.

The official CLIs — or its own

One codex app-server or claude -p process per agent, so your logins, sandboxes and model access keep working exactly as they do today. Where neither is installed, or for a swarm, bija ships beside mantra and needs nothing but an API key.

Tokens say what they cost

Every built-in pattern caps an agent’s context at 200k (context_cap), so the backend compacts there; QA starts from the diff instead of re-reading the repo; and every count shows its cached share — · 5.9M cached — so a big number reads as what it is.

A dead gateway wakes nobody

When the model gateway goes down, the run halts with the gateway’s own wording instead of waking the manager and the planner on the same dead gateway. space when it is back respawns every worker the outage took, where it was.

MODELS · PROVIDERS · BACKENDS

One place for every model, and the runtime it goes through.

An alias maps to a model and its backend — Codex, Claude Code or Bija. The same model via your Claude subscription and via a gateway are two clearly labelled rows. Any Responses-API provider works through Codex — OpenRouter verified end to end — and any OpenAI- or Anthropic-compatible API through Bija, a local server included. Discover a catalogue with D, test a model for real with t.

◌ codexastra · sol · terra · luna
✧ claudeopus5 · sonnet5 · fable51 · haiku45
• bijaastra-api · sol-api · terra-api · luna-api · any compatible API
⌁ gatewayopenrouter · libertai · any Responses-API host

BIJA · THE BUILT-IN HARNESS

A harness of its own. A key instead of a login.

Bija (bīja, a seed) is a small Rust binary that ships beside mantra and turns any OpenAI-compatible Chat Completions API — or an Anthropic-compatible Messages API — into a coding agent: file tools, commands with a timeout or in the background, every retryable API error retried with backoff. No Node, no login: a key, or none for a local server. It is Solo’s default, and any role can use it.

• solo defaultsol-api: the OpenAI API with OPENAI_API_KEY
↻ resumableevery message on disk as it happens; a crash resumes mid-turn
◆ swarm-sizedone thread, a few MB per agent — 32 workers are about 150 MB
$ standalonebija run, bija sessions, bija show <id> -f

Bija, in the docs →

~/.mantra/models.toml

# any compatible API — a local server needs no key
[[provider]]
id = "local"
kind = "bija"
base_url = "http://127.0.0.1:11434/v1"
wire = "openai"          # or "anthropic"

$ bija run --provider-url … --model … "fix the failing test"
$ bija show <id> -f   # follow a transcript

FROM ANY DEVICE

A web UI in the same process. A relay that never sees a byte of it.

--web serves an installable app for the same running session — chat with every agent, approve or answer from your phone, approve a plan, change a role’s model, watch the pulse feed — on your LAN or over HTTPS. --remote reaches it from anywhere through a relay that only ever forwards AES-256-GCM ciphertext: never your password, your key, or a byte of what an agent says.

◈ installablePWA on Android & iOS, offline shell, push notifications
◆ end-to-endthe relay is a blind byte pipe — one hosted session per public IPv4

Web UI & remote access, in the docs →

remote.mantra.codes/s/8f2c…#k=…

Scan, or open the link — the key travels only in the URL fragment, never to a server.

◇ amber-kite-river-nine

Code + password works too — read it aloud, or type it into a device you didn't get the link on.

Install

Installs two binaries side by side — mantra and bija, each checked against its sha256 — to ~/.local/bin, fixes your PATH, then runs mantra doctor. Re-run to upgrade.

{{ tabCmd }}

BACKENDS · BIJA SHIPS WITH MANTRA

• export OPENAI_API_KEY=… bija · Solo’s default

◌ npm i -g @openai/codex && codex login

✧ npm i -g @anthropic-ai/claude-code && claude

Bija is already there: a key and Solo runs on it — or point it at any other OpenAI- or Anthropic-compatible provider; a local server needs no key. Codex and Claude Code are optional. Plus git for worktrees. mantra doctor probes what is actually ready — app-server handshake, provider key accepted, sandbox runs a command — not just what is on PATH.

TRY IT · NO API CALLS, NO COST

$ mantra --demo

Real UI, real state machine, scripted agents — Bija talks to a mock API, no provider key needed. Press ctrl+o, type a goal, watch a full team run play out in about twenty seconds. Every screenshot on this page is demo mode.

1

Install

Paste the one-liner. mantra doctor runs at the end.

2

Open it in a repo

cd your-project && mantra — you're in Solo.

3

Summon the team

ctrl+o, describe the goal, approve the plan, /land.

→

Full docs

Keys, halts, patterns, providers, runs — on one page.

Questions, bugs, ideas.

Bugs and feature requests are happiest as GitHub issues. For everything else, the form opens your mail client — nothing is stored on a server. A quick automatic check in your browser keeps the address away from spam bots.

◎Open an issuegithub.com/sahelea1/mantra/issues↗

$Attach a support bundlecurl -fsSL https://raw.githubusercontent.com/sahelea1/mantra/master/support-bundle.sh | sh > mantra-bundle.txtVersions, doctor, settings, recent runs. Keys are redacted; nothing leaves your machine.

MANTRA

A team of agents, working as one.

Ask up. Never guess. Reach you only when it matters.

One agent, done properly.Or a whole team.

Everything you actually want on screen

A team that plans, builds and checks

Wider teams. Notes they share. Tools you give them.

Many small workers at once

Akasha: shared notes for agent groups

Your MCP servers, on all three backends

Screenshots, when the model asks

Why you might want it

Parallelism that is actually safe

Nothing silently stalls

It survives being closed

The official CLIs — or its own

Tokens say what they cost

A dead gateway wakes nobody

One place for every model, and the runtime it goes through.

A harness of its own. A key instead of a login.

A web UI in the same process. A relay that never sees a byte of it.

Install

Questions, bugs, ideas.

One agent, done properly.
Or a whole team.