Agents
What an agent is
Mint (the orb) talks with you and routes work. When a job is big (multi-step research, a long document, building code or a website, anything that produces files) Mint hands it to an agent and keeps talking to you while it works.
- Every agent has a name, a colour, a job, its own instructions, a set of tools, and a workspace folder in
~/Documents/Mint/agents/<name>. - Agents run on OpenAI GPT-6 Luna (through OpenRouter, or straight to OpenAI when that key is the one that works). Codex is OpenAI Codex itself.
- Mint only delegates when a job truly needs it: quick answers and anything on your screen it does itself.
Agents
The built-in agents
Astra
Research · owlet
- Does
- Searches the web, reads sources, cross-checks, writes a sourced brief
- Tools
- web search, read pages, files, ask you, progress
- Thinking
- medium
- Steps
- up to 24
Luna
Builder · bunny
- Does
- Code and RL environments: plans, writes complete runnable files, revises on request
- Tools
- files, web search, read pages, ask you, progress
- Thinking
- medium
- Steps
- up to 30
Sage
Writer · fox kit
- Does
- Long documents, reports and PDFs from notes or research
- Tools
- files, create PDF, ask you, progress
- Thinking
- low
- Steps
- up to 20
Codex
Coding · sprout
- Does
- Builds websites, apps and scripts in OpenAI Codex, runs and checks them, takes follow-up changes
- Runs
- the Codex inside the ChatGPT app, signed in with your ChatGPT account
- Folder
- a new one per build under
agents/codex/
Any agent you create gets a kitten, chick, baby dragon or bear cub, never the same species as one already out.
Agents
Giving an agent a job
Just ask for the result. Mint picks the right agent, or you can name one.
have Astra research the best mechanical keyboards and write a brief
ask Codex to make a tiny hello-world page
get Sage to write a two-page report on this, as a PDF
Luna and Astra, at the same time: Luna builds the gridworld, Astra finds three papers on reward shaping
give Astra what ChatGPT just wrote and have her check the sources
- Mint writes the brief. Full instructions (goal, constraints, what to deliver), how hard to think (none, low or medium), and why it needs an agent at all. Tasks under six words are refused as “do it yourself”.
- The critter pops out and the chat shows “Astra started: …”.
- It works in its own folder, with its own tools. You keep talking to Mint about anything else.
- When it finishes, Mint tells you the outcome, the chat shows it, and it goes into memory.
“Give Astra what ChatGPT just wrote” hands the agent the exact text of the window in front, links included, instead of Mint retyping it.
Agents
Reading the critters
| The agent | Its critter | In the chat |
|---|---|---|
| starts | The box wiggles, the lid pops, sparkles; it jumps out in a spinning arc, lands with a squish, shows its name | “Astra started: …” |
| thinks | A “…” bubble over its head | |
| uses a tool | The bubble shows it: magnifier (search), globe (page), pencil (writing), document (reading), folder, terminal, chart (progress) | |
| saves a file | A hop, a document bubble, a few stars | “Astra saved brief.md” |
| asks you something | A “?” bubble; it hops for attention; its tag says “click me” | “Astra asks: …” |
| gets your answer | A happy hop and hearts | |
| finishes | Happy eyes, a somersault, confetti; walks home and hops into the box | “Astra finished: …” ✓ |
| fails | A sad face, a rain cloud, a tear; trudges home | “… failed: …” ✗ |
| is stopped | A startled “!”, a quick dash home | “… stopped” ✗ |
The critters live in a gift box beside the orb, or on top of the chat when it is open. They never wander across your screen. The box disappears when the last one is home.
Agents
Talking to a working agent
| You want to | Say | What happens |
|---|---|---|
| Check on it | “how's Luna doing?” | agent_status: what each is doing, and who is helping whom |
| Answer its question | (just answer when Mint asks) | Mint wakes if asleep, asks you in its own words, passes your answer back |
| Change the plan | “tell Luna to use pytest”, “make it shorter” | It adapts at its next step. For Codex this works after it finished too: it continues the same project |
| Stop it | “stop Astra”, “stop all agents” | Stops it (and any helpers it brought in) |
| See them all | “what agents do you have?” | list_agents: name, job, model, current work |
how's Luna doing?
tell Luna to use pytest
make the brief shorter
stop Astra
stop all agents
what agents do you have?
Critters
Touching the critters
| Do | It does |
|---|---|
| Hover | Looks at you, hops, and its tag shows its name and what it is doing |
| Click | Hop and heart, a spin, a giggle, or its own species move; shows its status |
| Click one with a question, or double-click any | Opens the chat |
| Right-click | A menu: Open chat, Stop <name> |
| Click the box | Everyone hops and waves; the tag lists who is out |
| Poke five times quickly | It gets dizzy |
While Mint itself is clicking or typing (or just aimed a click), the critters let every click pass straight through, so they never catch a click meant for the app underneath. They are also hidden from Mint's own screenshots.
Agents
Agents working as a team
Mint gives a job to the agent best placed to lead. The lead brings in teammates itself when their specialty helps (Sage writing a report asks Astra for the research; Luna asks Codex to build something) and reports back for all of them.
ask Sage to write the report, and get the research from Astra first
have Luna build it, with Codex doing the web page
Sage, no helpers this time
| Rule | Detail |
|---|---|
| Folders | The lead's folder is the mission root; each helper works in helpers/<name>/ and can read everything, so nobody overwrites anybody |
| Team board | Agents share findings on a board (board.md); teammates working right now see new notes at their next step |
| Limits | 2 levels below the lead, 6 agents at once, no asking an agent already up your own chain, a helper stops after 20 minutes; stopping the lead stops its helpers |
| Your say | Mint can limit helpers (“only Astra”, or none) |
| Memory | Every finished run is logged; a new run starts with the most relevant earlier results and what Mint knows about you |
Agents
Making your own agent
create an agent called Nova that writes tweets, make it pink
make an agent that summarises papers, no web access
make Nova think harder
| Setting | Meaning |
|---|---|
| name | What you call it (and its critter's name tag) |
| role | One line: what it is for (Mint uses this to pick agents) |
| instructions | Its own system prompt: how it should work |
| thinking | none, low or medium (its usual effort) |
| web | Whether it may search the web and read pages (on by default) |
| colour | pink, purple, violet, teal, green, orange, amber, yellow, blue, red, cyan, mint, or a hex code |
Agents are kept in agents.json; edit it by hand if you like. Everyone gets files, asking you, and progress reports; web tools unless you say no.
Critters
Showtime
The whole critter family pops out of the toy box and performs: a stadium wave, a solo each, a dance to the beat, and a bow while Mint claps. Then they hop back in. About twenty seconds.
put on a show
party time
perform for me
concert!
Each species' own move
| Critter | Its move | Caption |
|---|---|---|
| Owlet (Hoot, Astra) | Tilts its head side to side | “hoo hoo!” |
| Bunny (Bun, Luna) | One ear flops over, then two thumps | “thump thump” |
| Sprout (Codex) | Leaves whirl like a propeller; it lifts off | “whirr!” |
| Fox kit (Kit, Sage) | Chases its tail | “chases its tail” |
| Kitten (Mochi) | A long lazy stretch, then a heart | “streeetch” |
| Chick (Pip) | Three quick pecks, wings flapping | “peck peck” |
| Baby dragon (Ember) | Puffs a tiny flame | “rawr!” |
| Bear cub (Teddy) | A big wave and hearts | “bear hug!” |
You also see these now and then while a helper waits, and sometimes when you click one. Real agents that are out during a show dance along.
Agents
Settings and troubleshooting
| Setting | Where |
|---|---|
| Critters on / off (off brings back small dots circling the orb) | Menu ▸ Cute critter helpers (sub-agents), after a restart |
| Agent keys | OPENROUTER_API_KEY and/or OPENAI_API_KEY in .env; Mint checks both at startup |
| Better web search for agents | EXA_API_KEY or TAVILY_API_KEY (DuckDuckGo otherwise) |
| Problem | Why, and the fix |
|---|---|
| Log says “openrouter: refused: API key expired” | Agents fall back to OpenAI directly. Renew the OpenRouter key with ./set-key.sh if you want it back |
| Codex won't start | Codex runs from inside the ChatGPT app; make sure ChatGPT is installed and signed in |
| An agent seems stuck | “how's Astra doing?”, then “stop Astra” if needed |
| Mint did it itself instead of delegating | Short or on-screen jobs are done by Mint on purpose. Name an agent to insist |