qalatra/docs/Writing agents

Writing your own agent

The hello-world, then three real examples.

Hello world

# ~/.qalatra/agents/hello/agent.config
name: hello
run: ./hello.sh
# ~/.qalatra/agents/hello/hello.sh
#!/usr/bin/env bash
echo "Hello from $QALATRA_TASK_ID"

Make it executable (chmod +x hello.sh), assign it to a task with &hello, select the task, press r. Done.

Example 1: call Claude Code

#!/usr/bin/env bash
# Read the task's title and notes, ask Claude for a plan.
TASK=$(curl -s $QALATRA_MCP_URL/tools/read_task \
  -H "Authorization: Bearer $QALATRA_MCP_TOKEN" \
  -d "{\"id\":\"$QALATRA_TASK_ID\"}")

echo "$TASK" | claude -p "Write an execution plan, max 5 steps."

Example 2: Python with the MCP client

#!/usr/bin/env python
from qalatra_mcp import Client
import os

mcp = Client(os.environ["QALATRA_MCP_URL"],
             os.environ["QALATRA_MCP_TOKEN"])

overdue = mcp.list_overdue()
for t in overdue:
    print(f"- {t.title} ({t.days_overdue}d)")

pip install qalatra-mcp for the official Python client.

Example 3: long-running with progress

#!/usr/bin/env bash
for f in src/**/*.md; do
  echo "PROGRESS: scanning $f"  # shows in task panel
  ./my-scanner "$f"
done
echo "Done. Scanned $(find src -name '*.md' | wc -l) files."

Lines prefixed PROGRESS: update the task's live status without appending.

Best practices

  • Exit 0 on success, non-zero on failure. Qalatra uses this to mark the task.
  • Print the real error, not "Something went wrong."
  • Use tools: in config to restrict MCP access.
  • Keep agents short and composable. If it's > 200 lines, split it.

Sharing

Agents are just folders. Push yours to a git repo, link it in the Agents community thread, or import from GitHub with qalatra agent add <git-url>. Marketplace is planned for v1.1.