Python Library

MonoClaw can be used as a Python library, not just a CLI. This lets you embed Mona into your own applications.

Installation

pip install monoclaw-runtime

Basic usage

from monoclaw import Agent

agent = Agent()
response = await agent.chat("What is the capital of France?")
print(response)

Using tools

from monoclaw import Agent

agent = Agent(tools=["file_read", "terminal"])

response = await agent.chat(
    "Read README.md and tell me what this project does"
)

Sessions

from monoclaw import Agent

agent = Agent()

# First message
response1 = await agent.chat("Remember my favorite color is blue")

# Second message (same session)
response2 = await agent.chat("What is my favorite color?")
# → "Your favorite color is blue."

# Save session
await agent.save_session("color-preference")

# Load later
agent2 = Agent(session="color-preference")

With skills

agent = Agent()
await agent.load_skill("kubernetes")

response = await agent.chat("Debug why this pod is crashing")

Batch processing

from monoclaw import batch_run

results = await batch_run(
    inputs=["What is 2+2?", "What is 3+3?", "What is 4+4?"],
    model="openai/gpt-5.4-mini"
)

for result in results:
    print(result)

Web app integration

FastAPI

from fastapi import FastAPI
from monoclaw import Agent

app = FastAPI()
agent = Agent()

@app.post("/chat")
async def chat(message: str):
    response = await agent.chat(message)
    return {"response": response}

Django

from django.http import JsonResponse
from monoclaw import Agent

agent = Agent()

async def chat_view(request):
    message = request.POST.get("message")
    response = await agent.chat(message)
    return JsonResponse({"response": response})

Configuration

from monoclaw import Agent

agent = Agent(
    model="anthropic/claude-sonnet-4",
    config={
        "terminal.backend": "docker",
        "memory.enabled": True
    }
)

Async vs sync

MonoClaw is async-first:

import asyncio
from monoclaw import Agent

async def main():
    agent = Agent()
    response = await agent.chat("Hello")
    print(response)

asyncio.run(main())

For synchronous environments:

from monoclaw import Agent

agent = Agent()
response = agent.chat_sync("Hello")
print(response)

Error handling

from monoclaw import Agent, MonoClawError

agent = Agent()

try:
    response = await agent.chat("Run rm -rf /")
except MonoClawError as e:
    print(f"Error: {e}")

Best practices

Reuse agents — Creating an agent is expensive; reuse when possible
Handle sessions — Save and load sessions for continuity
Set timeouts — Long-running chats can block:

response = await asyncio.wait_for(agent.chat("..."), timeout=60)

Clean up — Close agents when done:

await agent.close()