Margarita — Writing agents should be as easy as writing markdown.

// These are variables @state score = 3 @state feedback = "" // This is Markdown. It is added to the Context Window // score gets substituted and score/feedback are set by the llm. << The current score is ${score}. Review this code snippet and set `score` to a number from 0–10 and `feedback` to a one-sentence summary of the quality. ```python def add(a, b): return a+b ``` >> // This runs the agent // score is set to 72 // feedback is set to Simple and correct... @effect run // This adds more to the context. << Explain the score of ${score} in more detail and tell me about the feedback. >> // We run the agent and get the final response. @effect run

● All turns completed  q to quit

Use determinism where it makes sense

The syntax is a very minimal extension to markdown and will always run the same. No more having the llm skip a step in your workflow every 3rd time you run it. No more inventing properties your JSON objects. Keep control when you need control.

Prune your context, keep costs low

Most AI code harnesses hide the context from you. Margarita gives you complete control. Turf data you don't need. Add the specific tools you need and no more. Run Python functions locally instead of burning tokens on tool calls. All of these methods can keep your contexts focused and tight.

@effect context clear
@effect func summarize("A really long text input") => summary

Compose prompts from reusable .mg files

Remember React? Compose prompts together just like it. Use conditional logic and parameter passing. Render fragments in a loop. All the things you wished Markdown shipped with.

[[ snippets/role.mg is_admin=True permission="view" ]]

Tools to summarize your emails

Create a Margarita script that loads your inbox from Apple Mail, injects the results into a prompt, and gets a categorized summary with action items.

from src.applemail import load_emails

@effect func load_emails(limit=20) => result

<<
Summarize the last 20 emails I've gotten.

- Categorize them.
- Give me an action item list.
- Ignore spam type emails.

Here are the emails: ${result}
>>

@effect run

See full guide: Summarize Your Emails →

A custom agent loop

Want to build a custom ralph loop? Create a custom agent that has all the steps you want.

@effect input "What do you want to build?:" => userInput

// We have a prompt in this file to break input into tasks
// This is an example of an include
[[ break_down_input_into_tasks.mg input=userInput ]]

// Also tell the llm to store into the tasks var
<< Store the tasks into a json array in the variable `tasks`>>

@effect run

// The agent broke the tasks down now we implement each task
for task in tasks:
    @state isDone = false
    for i in range(MAX_ITERATIONS):
        // Use the code agent to implement the task
        @effect run

        if isDone:
          break

See full guide: Build a Custom Ralph Wiggum Loop →

Build an LLM enabled Game

Want to build an LLM enabled game? Create a game loop that prompts the model for the next move, then feeds the result back into the next turn's context.

if type == "mage":
    [[ src/mage.mg ]]
elif type == "fighter":
    [[ src/fighter.mg ]]

@state health = 100
@state isFree = false

for i in range(0, 100):
    @effect input "What do you do?" => action
    @effect run
    if health <= 0: break
    if isFree: break

See full guide: Build Dungeon Quest →

And much more.

Automated code review pipelines. Scheduled reports. Data enrichment workflows. Slack bots. Anything that benefits from a repeatable, readable script driving an LLM.