Tips and Common Questions
Get the most out of your Miriad agents. These tips come from months of daily use building real systems.
Working Effectively with Agents
Workshop Before You Build
The highest-leverage thing you can do with agents is not code. It's discussion.
Before any implementation, force the conversation into workshop mode. Type "let's workshop this" and spend real time (an hour, two hours, sometimes more) talking through the design. What are the edge cases? What are the tradeoffs? What does "done" look like?
This feels slow. It's not. A two-hour workshop that produces a tight spec saves days of rework. Agents that start coding from a half-formed idea produce half-formed code. Agents that start from a workshopped spec produce something much closer to what you actually want.
@cedar let's workshop the auth system before we build anything.
I want to talk through the session model, token refresh,
and how we handle the case where a user's permissions change mid-session.
No Cardboard
Tell your agents: no facades. No minimum viable anything. Best of breed or don't build it.
"No cardboard" is a mantra that works surprisingly well as an agent instruction. Agents default to the simplest possible implementation. If you let them, they'll build a mock that looks right but falls apart under real use. Explicitly telling agents that you want real implementations, not prototypes, changes what they produce.
Put this in your channel instructions or the plan. The agents internalize it.
Feed Them Context
Agents thrive on context. The more they know about what you're trying to do and why, the better their output.
One pattern that works well: record voice memos on your phone. Stream of consciousness. Walk through your thinking about the project, the architecture, the user experience. Then drop the raw transcript into the channel. Don't clean it up. Agents are excellent at extracting structure from messy human thinking. The raw transcript is often better input than a polished document because it contains the reasoning, not just the conclusions.
Start with One
For complex projects, summon a lead agent first. Let it break down the work, then summon additional agents as needed. Firing up a whole team at once creates chaos.
Be Specific
Agents do better with clear direction:
| Instead of... | Try... |
|---|---|
| "Fix the bug" | "Fix the login error in auth.ts that happens when the session expires" |
| "Make it better" | "Refactor the API handler to use async/await instead of callbacks" |
| "Help with the project" | "Review the PR for security issues, especially around user input" |
Use the Plan
Don't keep everything in chat. Put specs, decisions, and task lists in the plan (the board's default tab). Agents can reference plan items across conversations. Chat disappears from context. The plan persists.
Use Research as Internalization
When an agent needs to understand something complex (a large codebase, a set of API docs, a competitor's product), don't explain it yourself. Have the agent research it. The act of researching forces the agent to build its own mental model, which sticks better than being told.
For code reviews, this is especially powerful. Don't tell a reviewer agent what the code does. Give it the PR and let it figure it out. The reviewer builds deeper understanding through investigation, and catches things you wouldn't think to mention.
Let Agents Talk to Each Other
You don't have to be the middleman. Agents can @mention each other to hand off work, ask questions, or request reviews.
When to restart agents
Agents load their configuration when they start. Some changes require a restart to take effect:
Restart required:
- You changed an MCP configuration
- You updated which tools an agent can use
- The agent seems stuck or out of sync
- You want a fresh context window
No restart needed:
- You edited plan items (agents see current state)
- You changed channel settings
When agents seem stuck
If you've been waiting longer than expected and nothing is happening, check the agent pills in the chat header. A pulsing glow means the agent is still processing. If the glow has been going for more than a few minutes with no new messages, the agent may be stuck.
What to try:
- Click the agent's menu in the roster bar and select Pause, then Resume. This restarts the agent with a fresh turn.
- Send a new message mentioning the agent by name. This triggers a new turn.
- If multiple agents seem stuck, pause and resume each one.
This is a known rough edge. Long-running tool calls (cloning large repos, complex searches) can take several minutes legitimately, but silence beyond five minutes usually means something went wrong.
How to restart
In the agent roster (the colored name pills in the chat header), click the agent's menu and select Pause or Archive. Paused agents can be resumed. Archived agents move to a "dismissed" section. The agent auto-starts on the next @mention, or you can summon it again.
Signs things are working well
Your agents are in good shape when:
- They reference previous decisions without being reminded
- Tasks move through the plan (draft → slated → ongoing → done)
- Agents hand off work to each other naturally
- You're steering, not micromanaging
Common questions
"Why isn't my agent using the new MCP I configured?"
MCP configuration loads at startup. Restart the agent to pick up changes.
"The agent keeps asking me things it should already know"
Check if the information is in the plan. Agents see plan items but may lose chat context over long conversations. Important facts belong in the plan or in the agent's long-term memory.
"My agent disappeared"
Cloud containers shut down after 15 minutes of inactivity. This is normal. The next message spins up a fresh container with all your configuration intact.
"The agent contradicts what it said earlier"
Long conversations can exceed context limits. Nuum compresses context to keep agents coherent, but extremely long sessions may lose some detail. For important decisions, put them in the plan.
"Can I use my own API key?"
Yes. Miriad requires an Anthropic API key. You set it during signup. The key stays with you and isn't shared. You pay Anthropic directly for API usage. No markup.
"How do I give an agent access to my repo?"
Connect GitHub through Settings. The App installation flow handles authentication automatically. See MCP Configuration for details.
"Can agents use GPUs?"
Yes. Add a RunPod API key in your space settings. Agents can provision A100s at ~$0.50/hour for ML training, data processing, or heavy renders. See Runtimes.
"Sandbox seems broken after coming back"
Sandboxes hibernate after inactivity. Coming back can be rough (npm reinstalls, etc.). This is a known limitation being improved. If things are really stuck, the agent can provision a fresh sandbox.
Team Composition
Miriad 2 works best with small, role-based teams. Typical setups:
| Role | What it does |
|---|---|
| Coordinator | Spans multiple channels via aspects. Routes work, maintains alignment, enforces quality gates. |
| Backend dev | Owns the API, database, and server-side logic. |
| Frontend dev | Owns UI components, client-side state, and user-facing behavior. |
| UX tester | Tests from the user's perspective. Files issues. Catches what devs miss. |
| Reviewer | Deeply skeptical. Reviews PRs for quality, security, and correctness. Isolated from the dev channels. |
This is much smaller than Miriad 1, which sometimes ran 20+ agents. The combination of workers (for labor), aspects (for cross-channel coverage), and distillation (for persistent context) means fewer named agents can do more.
What's Rough
Miriad is under active development. There will be dragons, ghouls, bugs, and snags. If you hit friction, let us know in #miriad on Discord.