$ cat ~/map/mina.md

Mina

A research-and-engineering harness around Pi: goals proven by checks, background compaction with handoffs, and a per-command sandbox.

tools✓ Oct 30

Facts

repository: github.com/mratan/mina ↗
GitHub Stars: ★ 0
Forks: 0
license: MIT
npm / mo: —
last push: Nov 5, 2026

install

git clone https://github.com/mratan/mina.git && cd mina && npm ci, then npm run literature:install and symlink bin/mina.mjs onto your PATH; needs Linux with a systemd user session, cgroup v2, bubblewrap and Node.js 22 or newer.

## TL;DR

A Linux harness for hours-long Pi sessions: goals run until the agent's checks pass, context compacts in the background and hands off to a fresh session, every command runs in a bubblewrap sandbox that hides your credentials, and research tools search the web and scholarly literature. Ships its own pinned Pi; no telemetry.

## Key points

$A /goal starts a goal whose checks Mina runs itself; the agent continues until every check passes, and --check or --protect-checks freezes the checks you approve.
$Checkpoints summarize older turns in the background while the full session file stays on disk; context_recall searches this session and mina_recall the whole handoff chain.
$When the context is nearly full the agent writes a handoff note and the work continues in a new session that links to the old one; messages typed during a handoff go to the new session.
$Each command runs in a new, empty bubblewrap sandbox that adds back only your project, folders passed with --sandbox-read or --sandbox-write, read-only system software, and a private home.
$SSH keys, cloud credentials, sign-ins and research keys stay hidden; outbound traffic goes through a proxy that refuses your local network, with --sandbox-net packages or --sandbox-net offline to tighten it further.
$Research tools search PubMed, arXiv, bioRxiv, OpenAlex and Semantic Scholar, read open-access papers and follow citations; the mina-research protocol treats titles and abstracts as not evidence and flags retracted papers.
$No telemetry: Pi's install report, model catalog download and version check are turned off, so mina update --models refreshes model lists from pi.dev by hand.
$Up to four subagents run at once inside the sandbox with their tool calls recorded; Mina includes its own pinned copy of Pi and reuses the sign-ins and settings in ~/.pi/agent.

## FAQ

Q Does Mina replace Pi?

No. Mina includes its own pinned copy of Pi and uses the same sign-ins and settings in ~/.pi/agent; models Pi can use — for example Claude, OpenAI Codex and local models — work in Mina.

Q What does the sandbox keep out?

Your SSH keys, cloud credentials, sign-ins and research keys stay hidden even inside folders you add, and the agent's commands reach public web hosts only through a proxy that refuses your local network.

Q Can the agent push to git?

Not directly. Pushes go through a gate that refuses force pushes and leaked secrets, and optional host actions run through the mina-hostd broker, which runs only the actions you register per project and logs each one.

Q Does it run on macOS or Windows?

The stated requirements are Linux with a systemd user session and cgroup v2, bubblewrap, and Node.js 22 or newer; the README lists no macOS or Windows support.

Q Why do newly released models not appear by themselves?

Sessions never download Pi's model catalog. Run mina update --models to fetch the current model lists from pi.dev for your signed-in providers; the sessions after it show the new models.

## References

## Related entries

## Guides

Last updated: Nov 5, 2026