Baara: An Agentic Task Execution System on the Claude Agent SDK

Problem

Personal automation usually means a pile of brittle shell scripts and cron entries that nobody remembers the syntax for. I wanted to describe what I needed in plain language — “check my email every morning at 6am” — and have the system create the task, set the schedule, pick the right tools, and run it reliably without manual glue code.

Existing task runners assume you already know the schema: which tool to invoke, what cron expression to write, how to wire retries. That friction is exactly what keeps small automations from getting built. The motivation behind Baara (Mandinka for “work”) was to put a conversational agent in front of a real execution engine, so the agent handles intent translation while a proper backend handles scheduling, queuing, and failure.

Approach

I built Baara on Bun with Hono for routing and bun:sqlite for storage, integrating the Claude Agent SDK directly in-process. Rather than bridging to a subprocess, I expose 19 MCP tools through createSdkMcpServer() so the agent calls service functions directly — no HTTP self-calls or subprocess overhead. I originally prototyped in Rust but switched to TypeScript specifically to get this in-process SDK integration.

The chat layer streams responses token-by-token. Since the endpoint is a POST, I used streamSSE() server-side with includePartialMessages and consumed it in the browser via fetch + ReadableStream instead of EventSource.

The execution engine offers two modes: Direct for immediate single-machine runs, and Queued through a priority pipeline (P0 critical through P3 background, FIFO within tier) with at-least-once delivery and exponential backoff. Exhausted retries flag jobs for triage rather than failing silently.

Key Design Elements

• In-process MCP server — tools invoke service functions directly, no subprocess bridge
• Shared service layer — Web UI, CLI, and Croner-driven cron all consume the same logic
• JSONL execution logs — append-only, streamable, and jq-compatible, mirroring Claude Code’s pattern
• ~/.nexus/ data home — SQLite, logs, sessions, and briefings kept separate from ~/.claude/
• Defense in depth — API-key auth, exact-origin CORS, CSP headers, rate limiting, and clamped budgets/timeouts

Outcomes

• Unified three interfaces — chat, CLI, and cron — over a single service layer with no duplicated execution logic.
• Hardened the system through a three-analyst security review (frontend, backend, and LLM-specific threats), resolving all critical findings and most high-severity issues, including XSS escaping, CORS allowlisting, and budget caps against cost attacks.
• Reached a verified-clean state: zero tsc errors and 39+ Playwright cases, including user-story tests, passing.

Key Contributions

• Designed the chat-first architecture, making conversation the primary interface and the dashboard a secondary context panel.
• Implemented 19 MCP tools spanning task, job, queue, and status management for the agent to select from.
• Built the dual-mode dispatcher and queue manager with retry, triage, and health monitoring.
• Engineered real-time SSE streaming over POST and graceful shutdown with WAL checkpointing and orphaned-job recovery.
• Authored structured JSONL logging and a CLI (baara tasks, jobs, logs, status) over the shared service layer.