DEV Community: JigJoy

Build Your Own CLI Agent: A Step-by-Step Guide

Miodrag Vilotijević — Tue, 19 May 2026 16:24:01 +0000

I love JavaScript. Even though I have learned several languages, JavaScript has become my first choice when building new projects. In this post I'll walk through a small terminal chat app where a language model can run shell commands for you — something you can actually run locally. At the end there's a GitHub template if you'd rather clone than copy.

Two libraries do most of the heavy lifting:

Ink draws the chat in the terminal — the input box, scrolling text, and key handling — using React so you are not building a TUI from scratch.
Mozaik connects the model, tool calls, and conversation memory. Think of it as the wiring between "the model said something," "a tool finished," and "show that in the UI," so your screen code does not have to know every detail of the API.

Ink is what the user sees; Mozaik is what coordinates the agent behind the scenes.

What we are building

One Node command that:

Shows a simple chat UI in the terminal.
Forwards what you type to a hosted language model.
Lets the model run terminal commands through a single tool (run_command) when it needs to inspect the machine or run a build.
Prints the model's replies (and optional "calling a tool…" hints) in that same UI — without pushing API calls into every component.

The goal is a clean split: the terminal view stays simple; the agent and tools stay in one place and are easier to test or swap later.

How the pieces fit together

Mozaik runs everything on a shared AgenticEnvironment: when the model speaks, asks for a tool, or a tool returns a result, every piece that has joined that environment can hear about it. For this CLI you mainly care about two kinds of participant:

Role	Typical base class	Responsibility
Agent	`BaseAgentParticipant`	Remembers the conversation, asks the model for the next step, and runs tools (like `run_command`) when the model asks for them.
Observer / UI bridge	`BaseObserverParticipant`	Listens for assistant text and tool activity from the agent and forwards it into Ink through small callbacks — so the screen updates when the model speaks or starts a tool, without owning the agent loop.

In this project, typing in Ink calls session.send, which hands your text to the agent. You could add other participant types later (for example streaming stdin), but a straight send-to-agent path keeps the tutorial easy to follow.

┌─────────────┐     session.send()      ┌──────────────────┐
│  Ink (app)  │ ──────────────────────► │  TerminalAgent   │
└─────────────┘                         │  (agent loop)    │
       ▲                                └────────┬─────────┘
       │ callbacks                            │ join()
       │                                        ▼
┌─────────────┐                         ┌──────────────────┐
│  UIUpdater  │ ◄── onExternal* ─────── │ AgenticEnvironment│
│  (observer) │                         └──────────────────┘
└─────────────┘

Step 1 — Bootstrap the runtime (`cli.tsx`)

The entry file is intentionally tiny: load environment variables, maybe print a one-line usage hint, then hand off to Ink with render(<App />). Keep agent logic out of here — only bootstrapping.

#!/usr/bin/env node
import React from "react";
import { render } from "ink";
import meow from "meow";
import dotenv from "dotenv";
import path from "node:path";
import { fileURLToPath } from "node:url";
import App from "./app.js";

const here = path.dirname(fileURLToPath(import.meta.url));
dotenv.config({
  quiet: true,
  path: [
    path.resolve(process.cwd(), ".env"),
    path.resolve(here, "..", "..", ".env"),
    path.resolve(here, "..", "..", "..", ".env"),
  ],
});

meow(
  `
    Usage
      $ your-cli

    Starts an interactive chat with the agent.
`,
  { importMeta: import.meta },
);

render(<App />);

Step 2 — Compose the session (`session.ts`)

This file is the "control room." You create the model, the conversation memory, the thing that runs tools, and the shared environment, then plug in your agent and your UI helper. Everything with awkward names (OpenAIInferenceRunner, ModelContext, and so on) lives here so the React side stays small. When you are done, the UI only needs one method: send(message), forwarded to the agent's onMessage.

import {
  AgenticEnvironment,
  Gpt54,
  ModelContext,
  OpenAIInferenceRunner,
  DefaultFunctionCallRunner,
} from "@mozaik-ai/core";
import { terminalTools } from "./terminal/tools.js";
import { TerminalAgent } from "./terminal/agent.js";
import { UIUpdater } from "./ui-updater.js";

export type AgentSession = {
  send: (message: string) => void;
};

export type AgentListeners = {
  onAssistantText: (text: string) => void;
  onFunctionCall?: (name: string) => void;
};

export function createAgentSession(listeners: AgentListeners): AgentSession {
  const functionCallRunner = new DefaultFunctionCallRunner([...terminalTools]);
  const inferenceRunner = new OpenAIInferenceRunner();

  const context = ModelContext.create("cli-agent");
  const model = new Gpt54();
  model.setTools([...terminalTools]);

  const environment = new AgenticEnvironment();
  const agent = new TerminalAgent(
    inferenceRunner,
    functionCallRunner,
    environment,
    context,
    model,
  );
  const uiUpdater = new UIUpdater(listeners);

  agent.join(environment);
  uiUpdater.join(environment);
  environment.start();

  return {
    send: (message: string) => agent.onMessage(message),
  };
}

Step 3 — The agent loop (`terminal/agent.ts`)

This is the heart of the app. When someone sends a message, you record it, let the model think, and if it wants to run a tool you run it and feed the result back — then the model gets another turn until it answers in plain language.

In practice:

On new user text → add to conversation and ask for the next model response.
When the model asks for a tool → remember the call is in flight, run it, store the outcome.
When every outstanding tool has finished → ask the model again so it can either reply or request another step.

There is no Ink or terminal drawing in this file — only memory and orchestration — so you can change the UI later without touching the agent.

import {
  BaseAgentParticipant,
  UserMessageItem,
  FunctionCallItem,
  AgenticEnvironment,
  ModelContext,
  GenerativeModel,
  InputStream,
  InferenceRunner,
  FunctionCallRunner,
  FunctionCallOutputItem,
  DeveloperMessageItem,
} from "@mozaik-ai/core";

const programmaticAgentInputStub: InputStream = {
  async *stream() {},
};

export class TerminalAgent extends BaseAgentParticipant {
  private pendingCalls = new Set<string>();

  constructor(
    inferenceRunner: InferenceRunner,
    functionCallRunner: FunctionCallRunner,
    private readonly environment: AgenticEnvironment,
    private readonly context: ModelContext,
    private readonly model: GenerativeModel,
  ) {
    super(programmaticAgentInputStub, inferenceRunner, functionCallRunner);
  }

  override onMessage(message: string): void {
    const developerMessage = DeveloperMessageItem.create(
      `You are a terminal agent. You can run commands in the terminal to help the user with their request.`,
    );

    this.context
      .addContextItem(developerMessage)
      .addContextItem(UserMessageItem.create(message));
    this.runInference(this.environment, this.context, this.model);
  }

  override onFunctionCall(item: FunctionCallItem) {
    this.pendingCalls.add(item.callId);
    this.context.addContextItem(item);
    this.executeFunctionCall(this.environment, item);
  }

  override onFunctionCallOutput(item: FunctionCallOutputItem) {
    this.context.addContextItem(item);
    this.pendingCalls.delete(item.callId);
    if (this.pendingCalls.size === 0) {
      this.runInference(this.environment, this.context, this.model);
    }
  }
}

Step 4 — Tools the model can use (`terminal/tools.ts`)

Tools are how you tell the model what it is allowed to do outside of chat text. Each tool has a name, a short description the model can read, argument shapes, and an invoke function that runs on your machine.

Here we expose one tool: run_command, which executes a shell command and returns output so the model can use it on its next turn.

import { Tool } from "@mozaik-ai/core";
import { Terminal } from "./terminal.js";

const terminal = new Terminal();

export const terminalTools: Tool[] = [
  {
    name: "run_command",
    description: "Run a command in the terminal.",
    parameters: {
      type: "object",
      properties: {
        command: {
          type: "string",
          description: "The command to run in the terminal.",
        },
        cwd: { type: "string", description: "The current working directory." },
      },
      required: ["command", "cwd"],
    },
    strict: true,
    type: "function",
    invoke: async (args: { command: string; cwd: string }) => {
      const result = await terminal.runCommand(args.command, args.cwd);
      return result;
    },
  },
];

Step 5 — Feed the terminal UI (`ui-updater.ts`)

The observer sits between Mozaik and Ink. When the agent produces text the user should see, this class forwards it through a callback; when a tool starts, it can add a small status line (for example "calling run_command").

You stay subscribed to external events so you hear what the agent is doing, not duplicate the agent's own work — one clear owner of the loop and one clear owner of the display.

import {
  Participant,
  FunctionCallItem,
  ModelMessageItem,
  BaseObserverParticipant,
} from "@mozaik-ai/core";

type Listeners = {
  onAssistantText: (text: string) => void;
  onFunctionCall?: (name: string) => void;
};

export class UIUpdater extends BaseObserverParticipant {
  constructor(private readonly listeners: Listeners) {
    super();
  }

  override onFunctionCall(item: FunctionCallItem) {
    this.listeners.onFunctionCall?.(item.toJSON()?.name ?? "tool");
  }

  override onExternalFunctionCall(
    _source: Participant,
    item: FunctionCallItem,
  ) {
    this.listeners.onFunctionCall?.(item.toJSON()?.name ?? "tool");
  }

  override onExternalModelMessage(_source: Participant, item: ModelMessageItem) {
    const text = item.content?.text ?? "";
    if (text) this.listeners.onAssistantText(text);
  }
}

Step 6 — Wire Ink (`app.tsx`)

The Ink layer holds chat history in normal React state, builds the session once so you do not reconnect on every render, and on submit appends the user message then calls session.send. Anything the observer hears arrives through the callbacks you passed in when creating the session.

import React, { useMemo, useRef, useState } from "react";
import { useApp } from "ink";
import { createAgentSession } from "./session.js";

type ChatMessage = {
  id: number;
  role: "user" | "assistant" | "system";
  content: string;
};

export default function App() {
  const { exit } = useApp();
  const [messages, setMessages] = useState<ChatMessage[]>([]);
  const nextId = useRef(0);

  const appendMessage = (role: ChatMessage["role"], content: string) => {
    setMessages((previous) => [
      ...previous,
      { id: nextId.current++, role, content },
    ]);
  };

  const session = useMemo(
    () =>
      createAgentSession({
        onAssistantText: (text: string) => {
          appendMessage("assistant", text);
        },
        onFunctionCall: (name: string) => {
          appendMessage("system", `calling tool: ${name}`);
        },
      }),
    [],
  );

  const handleSubmit = (value: string) => {
    const trimmed = value.trim();
    if (!trimmed) return;
    appendMessage("user", trimmed);
    session.send(trimmed);
  };

  // …render messages + <TextInput onSubmit={handleSubmit} /> …
}

Step 7 — Credentials and build

Put your API key in .env (the template expects OPENAI_API_KEY; check Mozaik if you change model or provider). Then install, build, and run the compiled CLI (or npm link if you want a global command).

cp .env.example .env
# add OPENAI_API_KEY=sk-...

npm install
npm run build
npm start

Starter repository

Prefer a working tree over copy-paste? There is a template repo with the same layout this article walks through — agent, observer, tools, and Ink UI already split into files.

Scaffold a fresh project without copying the template's full git history:

npx degit jigjoy-ai/cli-agent-starter my-cli-agent
cd my-cli-agent
git init
git add .
git commit -m "Initial commit"
npm install

Replace jigjoy-ai/cli-agent-starter with your fork or canonical URL if it moves; replace my-cli-agent with your package name. Then edit package.json (name, bin), tweak source/cli.tsx / source/app.tsx branding, and start adding participants and tools.

GitHub alternative: enable Template repository in the repo settings and use Use this template — you get a first commit snapshot with a clean history for a new repo.

Starter template: github.com/jigjoy-ai/cli-agent-starter

Where to go next

Add BaseHumanParticipant if you want stdin streaming as first-class InputStream input.
Add a second BaseAgentParticipant and use onExternal* handlers to log or aggregate multi-agent chatter.
Swap Gpt54 / runners for other models supported by Mozaik as the ecosystem grows.

You now have a concise path from "blank Node project" to Ink front end + Mozaik event bus + tool-running agent — with a degit-friendly repo to hit the ground running.

Learn more

Mozaik: github.com/jigjoy-ai/mozaik

Read the full article on JigJoy: jigjoy.ai/blog/build-your-own-cli-agent

Reactive Agents, Typed Event Handlers, and Agent Swarms: What's New in Mozaik

Miodrag Vilotijević — Tue, 19 May 2026 13:31:10 +0000

When we released Mozaik v3, we introduced an event-based architecture where participants emit, observe, and react to typed context items inside a shared agentic environment. Since then, the framework has kept moving — and the way we think and talk about it has moved with it.

This post is a tour of what's new. The headline shift is conceptual: Mozaik is now framed around reactive agents — collaborative agents that adapt to their environment and to each other in real time. Underneath that frame, the API has gotten smaller, clearer, and easier to read.

From Non-Blocking to Reactive

Mozaik agents have always been non-blocking. That's still true — capability methods stream events as they're produced, so a slow inference or tool call never holds up other participants. But "non-blocking" describes a property, not a way of thinking.

The way we now think about Mozaik agents is reactive: an agent declares which events it cares about and reacts to them as they arrive — messages from humans, function calls from its own model, reasoning traces from a peer agent, or tool outputs from somewhere else in the environment. Behavior emerges from how agents react, not from a central controller deciding whose turn it is.

A reactive agent is event-driven, collaborative, and adapts to its environment and to other agents in real time.

This shift in framing pays off in design. Once an agent is a thing that reacts, adding behavior to a system stops being about editing a pipeline and becomes about joining another participant.

Typed Event Handlers

The biggest API change since 3.0 is on the participant side. In the original release, a participant exposed a single intercept point: onContextItem(source, item). You looked at the item, decided whether it came from you or someone else, and branched accordingly.

That worked, but it pushed a lot of dispatch logic into every agent. So we replaced the single intercept with a set of typed handlers, one per event kind:

onMessage
onFunctionCall
onFunctionCallOutput
onReasoning
onModelMessage

Each handler defaults to a no-op in the base class, so a reactive agent only writes the ones it actually cares about. The result is shorter, more declarative code — a reactive agent reads like a list of "when this happens, I do that," not like a switch statement.

Here is a full reactive agent built on top of BaseAgentParticipant. It records incoming messages, runs inference, executes its own tool calls, and keeps its local context in sync with what the model produces — all by overriding the handlers it cares about:

// reactive-agent.ts
import {
  BaseAgentParticipant,
  UserMessageItem,
  FunctionCallItem,
  FunctionCallOutputItem,
  ReasoningItem,
  ModelMessageItem,
  AgenticEnvironment,
  ModelContext,
  GenerativeModel,
  InputStream,
  InferenceRunner,
  FunctionCallRunner,
} from "@mozaik-ai/core"

export class ReactiveAgent extends BaseAgentParticipant {
  constructor(
    inputSource: InputStream,
    inferenceRunner: InferenceRunner,
    functionCallRunner: FunctionCallRunner,
    private readonly environment: AgenticEnvironment,
    private readonly context: ModelContext,
    private readonly model: GenerativeModel,
  ) {
    super(inputSource, inferenceRunner, functionCallRunner)
  }

  // A message from a human (or any other participant) — record it and think.
  async onMessage(message: string): Promise<void> {
    this.context.addContextItem(UserMessageItem.create(message))
    this.runInference(this.environment, this.context, this.model)
  }

  // The agent just produced a function call — execute it.
  async onFunctionCall(item: FunctionCallItem): Promise<void> {
    this.context.addContextItem(item)
    this.executeFunctionCall(this.environment, item)
  }

  // The tool just produced an output — feed it back and run inference again.
  async onFunctionCallOutput(item: FunctionCallOutputItem): Promise<void> {
    this.context.addContextItem(item)
    this.runInference(this.environment, this.context, this.model)
  }

  // Keep the local context in sync with model-emitted reasoning and replies.
  async onReasoning(item: ReasoningItem): Promise<void> {
    this.context.addContextItem(item)
  }

  async onModelMessage(item: ModelMessageItem): Promise<void> {
    this.context.addContextItem(item)
  }
}

For comparison, the old style looked like this:

// Before: one handler, manual dispatch
async onContextItem(source: Participant, item: ContextItem): Promise<void> {
  if (source === this) return

  this.context.addContextItem(item)

  if (item instanceof UserMessageItem) {
    this.runInference(this.environment, this.context, this.model)
    return
  }

  if (item instanceof FunctionCallItem) {
    this.executeFunctionCall(this.environment, item)
    return
  }
}

The Self vs. External Split

For every typed handler, there are two variants: a self handler that fires when this participant emits the event, and an external handler (prefixed with onExternal) that fires when another participant emits it.

Self (your emissions)	External (everyone else)
`onFunctionCall`	`onExternalFunctionCall`
`onFunctionCallOutput`	`onExternalFunctionCallOutput`
`onReasoning`	`onExternalReasoning`
`onModelMessage`	`onExternalModelMessage`

The practical effect: a reactive agent can encode "act on my own outputs" separately from "observe others" — no more manual source === this checks.

Want to build a critic that reviews a peer agent's answers? Override onExternalModelMessage.
Want to feed your model's own tool calls back into a runner? Override onFunctionCall.

The two concerns stop bleeding into each other.

As a concrete example, here is a passive participant that only listens to external events. It does not run inference and does not execute tools — it just watches what other participants emit and logs it. Drop it into any environment and you have a live transcript:

// transcript-logger.ts
import {
  Participant,
  FunctionCallItem,
  FunctionCallOutputItem,
  ReasoningItem,
  ModelMessageItem,
} from "@mozaik-ai/core"

export class TranscriptLogger extends Participant {
  async onMessage(message: string): Promise<void> {
    console.log("[message]", message)
  }

  async onExternalFunctionCall(
    source: Participant,
    item: FunctionCallItem,
  ): Promise<void> {
    console.log(`[${source.constructor.name}] function_call`, item.toJSON())
  }

  async onExternalFunctionCallOutput(
    source: Participant,
    item: FunctionCallOutputItem,
  ): Promise<void> {
    console.log(
      `[${source.constructor.name}] function_call_output`,
      item.toJSON(),
    )
  }

  async onExternalReasoning(
    source: Participant,
    item: ReasoningItem,
  ): Promise<void> {
    console.log(`[${source.constructor.name}] reasoning`, item.toJSON())
  }

  async onExternalModelMessage(
    source: Participant,
    item: ModelMessageItem,
  ): Promise<void> {
    console.log(`[${source.constructor.name}] model_message`, item.toJSON())
  }
}

Plain Messages on the Bus

Conversational text used to flow through the same context-item pipeline as everything else. It worked, but it was heavier than it needed to be. Now there are two clean lanes:

Messages — plain strings, delivered via onMessage(message: string). Use them for what a human types, what one agent says to another, and any other free-form text.
ContextItems — typed model internals (function calls, function call outputs, reasoning items, model messages), delivered via their dedicated handlers.

The participant side mirrors this: the old InputItemSource has become InputStream, an async iterable of strings. Each yielded string fans out via onMessage to every other participant. Inference and tool runners still produce typed ContextItems, exactly as before.

The benefit is mostly clarity. When you read a reactive agent now, you can tell at a glance whether a handler is reacting to "someone said something" or to "the model produced a tool call."

import { InputStream } from "@mozaik-ai/core"

// Async iterable of plain strings — each yield becomes onMessage for peers.
async function* humanInput(): InputStream {
  yield "Add rate limiting to all API endpoints"
  yield "Focus on the NestJS backend first"
}

A Bigger Model Lineup

The default OpenAI provider now ships a wider model lineup. In addition to Gpt54, Gpt54Mini, and Gpt54Nano, there is now Gpt55. Same OpenAIResponses runtime, same OpenResponses-aligned types — pick the model that fits the job.

import { Gpt55, Gpt54Mini } from "@mozaik-ai/core"

// Heavier reasoning for planning; lighter model for review passes.
const planner = new Gpt55()
const reviewer = new Gpt54Mini()

From One Agent to a Swarm

The reactive frame really earns its keep when more than one agent shares an environment. We've started calling these collaborative groups agent swarms: a handful of focused reactive agents — planner, executors, reviewer, and observers — all joining one AgenticEnvironment and reacting to each other's events.

Agent swarms — multiple reactive agents collaborating in one agentic environment

The clearest production example is baro, a Claude agent orchestrator built on Mozaik. Ten specialized participants — planner, executors, reviewer, fixer, librarian, auditor, and more — work fully concurrently on the same goal, like a team collaborating in real time instead of a single agent doing everything alone.

Adding a new role to a swarm doesn't mean editing a central controller. It means writing one more reactive agent and join()ing it to the environment. Everything else keeps working.

import { AgenticEnvironment } from "@mozaik-ai/core"

const environment = new AgenticEnvironment()

planner.join(environment)
executor.join(environment)
critic.join(environment)
new TranscriptLogger().join(environment)

environment.start()

Composing Intelligence

Each of these changes is small on its own. Together, they shift Mozaik further toward what we wanted from the start: a framework where intelligent behavior is something you compose, not something you orchestrate.

Change	What it unlocks
Reactive agents	Behavior from event handlers, not a central `run()` loop
Typed handlers	Readable "when X, do Y" agents without dispatch boilerplate
Self vs. external	Critics, observers, and actors coexist without `source === this`
Plain messages	Conversational text separate from model-internal ContextItems
Agent swarms	Many focused agents on one bus — see baro

Reactive agents make the building block explicit. Typed handlers make each agent easier to read. The self vs. external split keeps intent obvious. Plain messages keep the conversational lane clean. And the swarm pattern shows what falls out the other side: groups of agents that adapt to their environment and to each other in real time.

Get started

npm install @mozaik-ai/core

Star on GitHub: github.com/jigjoy-ai/mozaik

Read the full article on JigJoy: jigjoy.ai/blog/mozaik-reactive-agents

Structured Context, Context Memory, Context Item Generators, and the Agentic Environment

Miodrag Vilotijević — Tue, 05 May 2026 14:43:29 +0000

Mozaik started as a multi-provider library. With version 3.0.0, we are evolving it into a full TypeScript framework for building non-blocking AI agents.

This release introduces an event-based architecture designed around inversion of control. Instead of forcing developers into rigid, sequential pipelines, Mozaik enables humans, agents, observers, and tools to collaborate inside a shared agentic environment. Participants can emit, observe, and react to typed context items in real time, making multi-agent orchestration more flexible, composable, and concurrent.

Structured Context

Mozaik 3 introduces a structured, multi-provider context model compatible with the OpenResponses specification.

Instead of treating prompts as plain strings, Mozaik models context as typed items, including:

SystemMessageItem
DeveloperMessageItem
UserMessageItem
FunctionCallItem
FunctionCallOutputItem
ReasoningItem
ModelMessageItem

These context items help developers provide clearer, more precise instructions to language models. For example, combining system, developer, and user messages gives the model a better-organized context than placing everything into a single user message.

This structure also makes model interactions easier to inspect, store, replay, and adapt across providers.

Context Memory

Mozaik now models context as an aggregate of ordered context items through ModelContext.

This gives developers a structured foundation for both short-term working memory and long-term persistence. The framework includes a repository interface, allowing context to be saved and retrieved through different storage backends.

Mozaik provides an in-memory implementation for working memory, while developers can implement their own repositories for file systems, databases, or other persistence layers.

This approach keeps memory explicit, portable, and provider-independent.

Context Item Generators

Mozaik 3 introduces asynchronous context item generators for key parts of the framework, including input handling, inference, and function call execution.

Instead of relying on blocking await chains, runners can produce context items over time through async iterables. This enables items to be generated and delivered in real time while giving developers control over when and how those streams are consumed.

Mozaik provides default implementations for function call execution and OpenAI inference. Developers can also create their own implementations, which is especially useful for testing, mocking runners, customizing tool execution, or adding support for additional model providers.

Agentic Environment

The main goal of Mozaik 3 is to enable AI agents to collaborate in a non-blocking way.

We believe that truly agentic systems should not be limited to sequential chains. In many real-world use cases, agents need to observe, react, and contribute concurrently.

To support this, Mozaik introduces the Participant abstraction and the AgenticEnvironment.

Participants join the same environment and react to typed context items as they arrive.

Participants, including humans and agents, join the same environment and subscribe to context items generated by other participants. When one participant emits a context item, other participants can observe it, react to it, ignore it, or use it to update their own internal context.

or example, a human can send a UserMessageItem into the environment. One or more agents can react by running inference, producing model messages, requesting function calls, or incorporating the new item into their own context. Other agents can observe those outputs and respond with their own contributions.

This enables agents to work in parallel and remain aware of what other participants are doing during inference.

Default Participants

To make multi-agent development faster, Mozaik 3 also includes default participant implementations:

BaseAgentParticipant
BaseHumanParticipant

These base classes provide common capabilities for generating, receiving, and reacting to context items, so developers can set up multi-agent systems with less boilerplate while still keeping full control over the architecture.

A Foundation for Multi-Agent Systems

Mozaik 3 moves beyond simple provider abstraction.

It introduces a framework-level architecture for building reactive, non-blocking, context-aware AI systems. By combining structured context, explicit memory, async context item generation, and a shared agentic environment, Mozaik gives developers the building blocks for more flexible and scalable multi-agent applications.

With version 3.0.0, Mozaik becomes a foundation for building agents that do not just run in sequence, but collaborate through shared context in real time.

Star on GitHub: https://github.com/jigjoy-ai/mozaik

Why Agent Frameworks End Up As SDK Wrappers - And How To Overcome It

Miodrag Vilotijević — Thu, 16 Apr 2026 07:48:43 +0000

Today, most frameworks for building AI agents are missing something fundamental. If you look closely at the language they use, you'll notice a pattern: their domain models are anemic. They give you abstractions like "agent", "tool", "step", but they don't actually model the thing that matters most - context. Because of that, developers are left on their own to deal with problems like:

context window overflow
context bloating
loss of structure across multiple model calls
messy handling of tool outputs and reasoning

And where does all of that logic end up? In your application layer.

The Hidden Cost: Polluting Your Domain

Instead of focusing on your actual domain (finance, healthcare, internal tooling, etc.), you start writing code like:

guessing what the model "needs to see" next
use your own way and schema to persist context
load context with schema which is not most efficient way to do it
and so on...

This is not your domain. It's not even context engineering. In the absence of the right abstractions, developers are pushed to reimplement core LLM concepts themselves - while mixing them with their own domain logic. And this is where complexity arises. We experienced these issues firsthand. That’s what pushed us to address them—so engineers like us can extract more from LLMs and open up new possibilities.

The goal with Mozaik is simple:

Enable developers to use a rich domain model for handling context in agentic applications.

So instead of letting LLM concerns leak into your domain, you can:

keep your domain logic isolated and aligned with best practices
use standardized building blocks to build your own context model
don't spend time reinventing the wheel
and hopefully, enjoy the process

At the same time, this is a space we're actively learning in. LLMs are still evolving, and we want to both learn and share what we discover while working on these problems.

Starting Point: OpenResponses

We didn't start from scratch.

Our starting point is the OpenResponses specification, published by companies like OpenAI, OpenRouter, Vercel and others in January this year. Their goal is to standardize how we work with LLM providers. They define a shared structure that reflects how models actually operate.

At its core:

Context is composed of context items.

These include:

Client-created items

user message
developer message
function call output

Model-generated items

reasoning
function call
model message

They also introduce an important idea:

Model-generated items are state machines that can be streamed with semantic events.

Those are the fundamental building blocks of the OpenResponses specification and how major LLM providers implement them. For a deeper dive, you can check: https://www.openresponses.org/

Our Take on This

OpenResponses gives us the source of truth for how LLMs work today. These building blocks should not be ignored. But the specification itself is not enough. Developers still need a way to work with it in practice.

Enter Mozaik

Our approach is to take this specification and turn it into a rich object domain model. The goal is not to abstract everything away, but to:

make context explicit
make it composable
make it persistent
make it evolvable across multiple steps

With our base implementation, developers can:

build structured context from typed items
manage model-generated items (reasoning, function calls, outputs)
persist context
restore it and continue execution

All without leaking context engineering concerns into their core domain logic.

Where This Leads

We see this as a starting point.

By introducing a richer domain model for context, new opportunities open up:

better strategies for context compression
smarter handling of long-running interactions
clearer debugging and observability
more predictable and controllable multi-agent systems

Basic Example

Here's a minimal example of building and storing context using Mozaik:

const contextRepository = new InMemoryContextRepository()

const message = UserMessage.create("Tell me a joke about birds")
const developerMessage = DeveloperMessage.create(
  "You are a joke teller. You will be given a joke and you will need to tell it to the user.",
)

const projectId = `pr-${crypto.randomUUID()}`

const context = Context.create(projectId)
  .addItem(developerMessage)
  .addItem(message)

await contextRepository.save(context)

const model = new GPT54Model()
const generatedItems = await model.call(context)
context.addItems(generatedItems)
await contextRepository.save(context)

const restoredContexts = await contextRepository.getByProjectId(projectId)
console.log(restoredContexts)

This uses an in-memory repository, but in real applications you can plug in your own persistence layer.

You can find more working examples in the GitHub repository:

github.com/jigjoy-ai/mozaik-examples

Final Thought

The industry is moving fast. But if we keep ignoring context as a core primitive, we'll keep rebuilding the same fragile systems. Mozaik is our attempt to fix that - by giving context the place it actually deserves. And this is just the beginning. We're excited to see where this journey takes us.

If you like what we’re building, give Mozaik a ⭐ on GitHub.

jigjoy-ai / mozaik

Mozaik is an open-source TypeScript framework for building event-driven AI agents.

Mozaik

Mozaik is an open-source TypeScript framework for building AI agents that share an agentic environment instead of being orchestrated through rigid pipelines.

In Mozaik, humans, agents, observers, and tools are all Participants of the same AgenticEnvironment. Each participant runs non-blocking and streams typed ContextItems into the environment. Every other participant sees those items in real time and can react, intercept, or stay silent — without any central scheduler.

Installation

yarn add @mozaik-ai/core

API Key Configuration

# .env
OPENAI_API_KEY=your-openai-key-here

The agentic environment

AgenticEnvironment is a broadcast bus for typed context items. Participants join() it, and any item produced by one participant is delivered to every subscriber's onContextItem(source, item) callback.

flowchart LR
    Human[BaseHumanParticipant] -->|streamInput| Env(("AgenticEnvironment"))
    Agent[BaseAgentParticipant] -->|"runInference / executeFunctionCall"| Env
    Observer[Custom Participant] -->|join| Env
    Env -->|onContextItem| Human
    Env -->|onContextItem| Agent
    Env -->|onContextItem| Observer

Non-blocking participants

Mozaik ships two ready-to-use participants:

Participant	Capabilities	Pulls from

…

View on GitHub

Spektrum: Turn Natural Language into Live Web Apps (Deploy in Minutes with AI)

Hadil Ben Abdallah — Tue, 24 Mar 2026 06:01:30 +0000

Turn a single prompt into a fully deployed web app in minutes, no setup, no infrastructure, no friction.

If you’ve ever tried to turn an idea into a working product, you already know that writing code is only a small part of the journey. The real friction usually comes from everything around it: setting up the project, deciding on the architecture, connecting services, deploying, and then iterating when things break.

At some point, what started as an exciting idea slowly turns into a process. And that process often kills momentum.

But what if you could skip most of that?

What if you could simply describe what you want to build in plain English and get back a live, deployed web application?

That’s exactly what Spektrum is designed to do.

This represents a new wave of AI app generation, where natural language becomes the interface for building real products.

What Is Spektrum?

Spektrum is a vibe coding SDK that transforms natural language into fully functional, deployed web applications. Instead of manually writing and wiring everything yourself, you define your intent, and the system takes care of execution.

In practice, that means you can describe an idea, let the AI generate the code, and receive a publicly accessible app URL in return. It’s not just a code generator; it’s a system that handles the entire lifecycle from idea to deployment.

What makes this interesting is that Spektrum doesn’t stop at generating code snippets. It actually produces complete, runnable applications that you can use, share, or integrate into your own products.

This makes Spektrum a powerful tool for AI app generation, turning natural language into web apps without traditional setup overhead.

What You Can Do with Spektrum

Spektrum opens up a faster way to go from idea to execution without getting blocked by setup or infrastructure decisions. Whether you're exploring a new concept or building something real, it lets you focus on the outcome instead of the process.

With Spektrum, you can:

Turn ideas into working web apps instantly
Build MVPs without setup overhead
Generate production-ready UI from natural language
Experiment with new product ideas quickly

This makes Spektrum especially powerful for developers who want to move fast without sacrificing real output.

Why This Matters (More Than You Think)

Before AI tooling became mainstream, teams relied heavily on planning methodologies to manage complexity. Approaches like specification by example and domain-driven design helped bridge the gap between ideas and implementation, but they still depended heavily on human coordination.

Even today, many AI tools inherit similar problems. Context gets lost between steps, developers are still responsible for managing state, and deployment pipelines remain a separate concern.

Spektrum takes a different approach by collapsing these steps into a single flow. Rather than treating coding, infrastructure, and deployment as separate phases, it handles them as one continuous process.

Compared to traditional development workflows, Spektrum removes multiple layers of setup, making the path from idea to working product significantly shorter.

The result is not just faster development, but a fundamentally different way of thinking about building software.

Explore Spektrum

Key Features That Make Spektrum Different

Spektrum isn’t just about generating code faster. It introduces a model powered by AI coding agents that handle execution, state, and deployment behind the scenes.

Here are some of the key capabilities that make that possible:

Coding Agents in the Cloud

One of the most important aspects of Spektrum is that it removes the need to manage infrastructure or execution context manually. The system handles state, code generation, and deployment in the background, allowing you to focus entirely on what you want to build.

Real-Time Monitoring

Spektrum also provides visibility into the process. You can track how your application is being generated, monitor deployment progress, and access logs when needed. This makes the system feel less like a black box and more like a collaborative tool.

From Idea to Production in Minutes

Many tools promise speed, but still require significant setup before you see results. Spektrum reduces that gap dramatically by combining project creation, task definition, and deployment into a single streamlined workflow.

Flexible, Usage-Based Pricing

The pricing model is also designed to encourage experimentation. With a token-based system and an average cost of around $0.50 per app generation, it becomes easy to test ideas without committing to heavy infrastructure costs.

How Spektrum Works (From Prompt to Live App in a Few Lines)

Using Spektrum feels surprisingly minimal. The workflow is intentionally simple, which makes it easy to experiment without dealing with setup overhead.

Here’s what that looks like in practice:

import { SpektrumSDK } from "@spektrum-ai/sdk"

const spektrum = new SpektrumSDK()

const project = await spektrum.createProject("portfolio-website")

const task = await spektrum.createTask(
  project.id,
  "Create a portfolio website for a software engineer"
)

await spektrum.codeAndDeploy(task)

const appUrl = await spektrum.getAppUrl(project.id)

console.log(`Live at: ${appUrl}`)

In simple terms:

You describe what you want
Spektrum generates the code
The app is deployed automatically
You get a live URL

At a high level, this represents a new way of building software, where natural language to web app generation becomes a practical and repeatable workflow.

What stands out here isn’t just the small amount of code. It’s the fact that everything behind the scenes, including code generation, environment setup, and deployment, is handled automatically.

This is where the experience starts to feel fundamentally different from traditional development workflows.

Getting Started with Spektrum (Two Ways)

One thing I appreciated while testing Spektrum is that it doesn’t force you into a single workflow. Depending on how you prefer to build, you can either integrate it programmatically using the SDK or use the platform directly through a visual interface.

If you’re a developer looking to embed app generation into your own product, the SDK approach gives you full control. But if your goal is to quickly test ideas, validate concepts, or just experience how fast this workflow can be, the platform UI is by far the fastest way to get started.

Option 1: Using the SDK (For Integration)

If you want to integrate Spektrum into your own application or automate workflows, you can use the SDK.

npm install @spektrum-ai/sdk

Spektrum requires Node.js 20.6.0 or higher, mainly because of modern runtime features like --env-file support.

Next, create a .env file at the root of your project and add your API key:

SPEKTRUM_API_KEY=your_api_key_here

You can get your API key by signing up on the JigJoy platform.

Once your environment is set up, you initialize the SDK:

const spektrum = new SpektrumSDK()

From there, everything revolves around two core concepts: projects and tasks.

A project is a container for your application
A task is a description of what you want to build

When you call createTask, you’re not just passing a title; you’re defining the intent and structure of your application. The more precise your description is, the better the result will be.

After defining the task, calling codeAndDeploy triggers the full pipeline:

The AI interprets your request
Generates the codebase
Prepares the environment
Deploys the application

Finally, getAppUrl returns a live, publicly accessible URL where your app is already running.

At that point, you’re no longer in a “development phase.” You already have a working product you can test, share, or iterate on.

This flow gives you full flexibility, especially if you're building something more advanced or integrating AI-generated apps into your own system.

Option 2: Using the Spektrum Platform (What I Actually Used)

In my case, I wanted to experience Spektrum the same way most developers would when discovering a new tool: quickly, without setup, and without reading too much documentation upfront. So instead of starting with the SDK, I used the Spektrum platform UI directly.

The flow is surprisingly simple and removes almost all friction.

When you open the platform, you’re guided through a step-by-step onboarding flow.

Step 1: Generate an API Key

The first step is generating your API key. Instead of manually creating environment variables or configuring anything locally, you simply click a button and the platform handles it for you.

Generate your API key directly from the platform

Within seconds, your key is generated and displayed, ready to be used if you want to switch to the SDK later.

Your API key is instantly created and ready to use

Step 2: Create Your First Project

Next, you create your first project. This acts as the container for everything you’re about to build.

Create your first project with a single click

Again, this doesn’t require writing anything manually. You can either run the suggested snippet or simply use the interface, and within a few seconds, your project is ready.

A project is created with a ready-to-use environment

Step 3: Create Your First Task

Once the project is created, the next step is defining a task.

This is where you describe what you want to build. And you can run multiple tasks within the same project.

Define what you want to build using a task

What’s interesting here is that you’re not thinking in terms of components or files. You’re defining intent, and the system takes care of translating that into an actual application.

First task is created with a single click

Step 4: Generate and Deploy the App

Once the task is defined, you simply run it.

This is the point where everything comes together.

You simply click a button, and Spektrum:

Interprets your request
Generates the full codebase
Prepares the environment
Deploys the application

Generate and deploy your first app

Within seconds, the app is built, deployed, and accessible through a live URL.

Application generated and deployed

There’s no setup, no configuration, and no deployment pipeline to manage. The entire process feels more like interacting with a system than building software in the traditional sense.

My Experience: Building a Real App with Spektrum

Instead of over-engineering the prompt, I kept it intentionally simple to see how far Spektrum could go on its own.

This was my prompt:

Create a gamified app for learning Japanese vocabulary

That’s it. One sentence.

What happened next is what genuinely surprised me.

Spektrum didn’t just generate a basic app based on that input. It expanded the idea into a fully structured experience, automatically designing a complete gamified Japanese vocabulary dashboard with multiple sections, including a hero area, progress tracking, a lesson quest path, daily missions, featured flashcards, and a leaderboard.

It also introduced reusable UI components like buttons, cards, badges, and progress indicators, along with utility helpers and polished global styling, without me explicitly asking for any of that.

In other words, it didn’t just execute the prompt. It interpreted the intent behind it and filled in the gaps like an experienced developer would.

This felt like the system was making product-level decisions, not just generating code.

Real-time monitoring showing how Spektrum interprets and builds beyond the initial prompt

A fully structured gamified app generated from a single-sentence prompt

Then I just clicked the "Deploy" button and my app was live in a few seconds. It honestly took less than a minute 😅

🚀 Try the Live App I Built

What stood out to me wasn’t just the speed, but how complete the result felt from the first iteration. The layout was structured and the UI didn’t feel randomly stitched together.

More importantly, iteration was simple. Instead of rewriting code, I could refine the prompt, adjust the requirements, and regenerate the app. That shift alone changes how you approach building.

You spend less time managing implementation details and more time thinking about the product itself.

Who Is Spektrum For?

Spektrum isn’t about replacing developers. Instead, it focuses on removing the friction that slows them down, especially in the early stages of building.

It’s particularly useful for developers building MVPs, indie hackers exploring new ideas, startups validating features, or teams looking to integrate app generation into their own platforms.

Common use cases include:

Rapid MVP prototyping
Internal tools generation
AI-powered product features
Experimenting with new ideas quickly

If your workflow often includes the thought, “This will take a few hours to set up before I even start building,” Spektrum changes that dynamic completely.

A Small Note for the Community 💙

If you’ve been exploring Spektrum or thinking about building with it, joining the JigJoy Discord is a great way to connect with the team, ask questions, and see what others are building in real time.

💬 Join JigJoy on Discord

If this project sparked your interest or gave you ideas, dropping a ⭐ on the repo is one of the simplest ways to support the team and help it reach more developers.

⭐ Star Spektrum on GitHub

Final Thoughts

There’s a moment every developer remembers when an idea turns into something real and working. It’s the moment where everything clicks, and the effort suddenly feels worth it.

Spektrum is trying to bring that moment closer by removing the layers that slow developers down. It doesn’t replace creativity or problem-solving, but it reduces the friction between intention and execution.

If the current direction of AI development continues, we may not just be writing code in the future. We may be describing systems and watching them come to life.

Tools like Spektrum aren’t just improving development. They’re redefining how software gets built.

Thanks for reading! 🙏🏻 I hope you found this useful ✅ Please react and follow for more 😍 Made with 💙 by Hadil Ben Abdallah

Hadil Ben AbdallahFollow

Software Engineer • Technical Writer (250K+ readers) I turn brands into websites people 💙 to use

From Monolith to Microservices: How Bounded Context Improves AI-Driven Development

Miodrag Vilotijević — Fri, 20 Mar 2026 17:44:03 +0000

Introduction

When we first launched our vibe coding platform, the architecture started as a single monolithic application. Initially this approach allowed us to move quickly and ship features fast.

But as the platform grew, the warning signs appeared.

The codebase became increasingly complex, new features were harder to implement, and development velocity began to slow down. What once felt manageable started to evolve into a tightly coupled system that was difficult to reason about.

To solve this, we made a strategic decision: refactor the platform from a monolith into a microservices architecture.

In this article we explain:

Why monolithic architectures struggle in AI-driven systems
How Domain-Driven Design (DDD) helps define system boundaries
Why bounded contexts are critical for AI agents
How we split our platform into eight microservices

This architectural shift significantly improved both developer productivity and AI agent performance.

Understanding Domain-Driven Design

The concept of Domain-Driven Design (DDD) was introduced by Eric Evans in the influential book Domain‑Driven Design: Tackling Complexity in the Heart of Software.

Although the book was published in 2003, its ideas remain extremely relevant today. Many modern architectural patterns—including microservices—are heavily inspired by DDD principles.

DDD focuses on one core idea:

Software architecture should mirror the structure of the business domain. Instead of organizing systems purely around technical layers, DDD encourages teams to structure software around real business capabilities and concepts.

While doing domain distillation, we detected the 6 main bounded contexts that can act as independent services: project planning, AI coding, project deployment, version control, observability, account and billing.

The Monolith vs Microservices Debate

For years developers have debated a fundamental architectural question:

Should applications remain monolithic, or should they be broken into microservices?

Monoliths have advantages:

Simpler deployments
Easier early development
Fewer distributed systems challenges

However, as systems scale, monoliths often become harder to maintain. Large codebases accumulate complexity and eventually turn into what developers often call a "Big Ball of Mud."

Today the conversation has evolved even further. We are no longer building systems only for human developers. We are building systems that AI agents interact with, modify, and reason about. And this introduces a new challenge.

Why Monolithic Architectures Confuse AI Agents

AI agents rely heavily on clear context boundaries.When a system grows into a large monolithic repository:

Domain concepts overlap
Terminology becomes ambiguous
Architectural boundaries blur

This makes it harder for AI systems to correctly interpret intent. For example, an AI agent might receive a command such as:

Create a project.

In a large monolith, the term project might refer to several different things:

A planning workspace
A source code repository
A deployment environment

Without clear boundaries, the AI agent must guess the meaning. And guessing leads to errors. This is why architectural clarity matters even more in AI-driven development environments.

What Is a Bounded Context?

A Bounded Context is a central concept in Domain-Driven Design. It defines a clear boundary within which a specific domain model applies and terminology has a single meaning.

Inside a bounded context:

Language is consistent
Concepts are clearly defined
Domain logic belongs only to that context

This creates a shared understanding between:

Developers
Domain experts
AI agents

Each context effectively becomes its own mini-world with well-defined rules.

Why Bounded Contexts Improve AI Development

In large software systems, the same word can mean different things in different domains. While building our AI coding platform, we encountered this problem quickly. Consider the word project.

When both meanings existed in the same codebase, confusion spread. Not only for engineers—but for AI agents operating within the platform. By introducing bounded contexts, we ensured that each domain defines its own terminology and behavior. This dramatically improved the reliability of both human workflows and AI-generated development tasks.

Our Microservices Architecture

After refactoring the platform using Domain-Driven Design principles, we divided the system into eight bounded contexts, each implemented as a separate microservice.

This allowed each domain to evolve independently while maintaining clear system boundaries.

Project Planning Context - manages planning activities. Within this domain we store: tasks, projects, agent which generate tasks...
AI Coding Context - this is where development actually happens. AI coding agents operate in this domain and perform tasks such as: writing code, committing changes, managing development workflows.
Project Deployment Context - manages the infrastructure and pipelines required to deploy software built by AI agents.
Version Control Context - while platforms like GitHub provide robust version control, we chose to build a lightweight internal system optimized specifically for AI-driven development workflows.
Observability Context - collects events and analytics from across the platform.
Account and Billing Context - manages user accounts, platform credits, payments.
API Gateway - acts as the central entry point into the platform.
Platform UI - provides the user interface that connects all services together.

Avoiding the Big Ball of Mud

Without clear architectural boundaries, complex systems eventually degrade into tightly coupled codebases that are difficult to maintain. Developers often describe this situation as a "Big Ball of Mud."

Symptoms typically include:

Spaghetti code
Increasing bugs
Slower development cycles
Poor onboarding experience
Confusing system behavior

For AI-driven platforms, the consequences are even worse because agents lose the contextual clarity required to generate reliable code.

By organizing our platform around bounded contexts and microservices, we achieved several key benefits:

Clear domain ownership
Faster feature development
Better system scalability
Improved AI agent performance
More maintainable architecture

Final Thoughts

As AI agents become increasingly involved in software development, architecture design must evolve alongside them. Bounded contexts and microservices are no longer just about scaling engineering teams—they also help AI systems reason about complex software platforms. For us, adopting Domain-Driven Design and microservices architecture transformed a growing monolith into a scalable platform designed for the future of AI-assisted development.

Multiple models are in play on any large project. Yet when code based on distinct models is combined, software becomes buggy, unreliable, and difficult to understand.

— Eric Evans

Why a Single Interface for Multiple LLM Providers Is a Bad Design Decision

Miodrag Vilotijević — Thu, 19 Mar 2026 06:29:02 +0000

Don't write frameworks for dummies.

That sentence stuck with me while reading Domain-Driven Design: Tackling Complexity in the Heart of Software. I didn't fully understand it at first - but after building (and then redesigning) an AI orchestration framework, I do now.

Where We Started

When we began building a framework for orchestrating AI agents, one of the first features we introduced was a unified request interface across multiple LLM providers.

At first, it felt like a great design decision.

One interface.
Multiple providers.
Clean abstraction.
Simple.

But that simplicity turned out to be misleading.

The Problem with "Unified" Abstractions

Over time, cracks started to show:

All models looked the same to developers

By flattening everything into a single interface, we erased the differences between models. Developers stopped thinking about capabilities and limitations - which is exactly what they should be thinking about.

Adding new models became harder, not easier

New models come with new capabilities, parameters, and behaviors. A "unified" interface either ignores those features, or becomes bloated trying to support everything. Neither is good design.

The ubiquitous language was wrong

The API didn't reflect the domain. It reflected our attempt to simplify it. That meant the language of the library didn't express real model capabilities.

We enabled misuse by design

The worst part: the abstraction allowed developers to make mistakes easily - and only discover them at runtime.

For example:

passing reasoning_effort="high" to a model that doesn't support reasoning.

The system didn't prevent it. It allowed it.

That's not just a bad developer experience - it's a failure in design. The abstraction wasn't helping developers. It was hiding the truth.

The Redesign

So we changed direction.

Instead of forcing a unified interface, we started modeling each LLM separately, along with its capabilities and constraints.

Why This Is the Right Move

Advanced users can extract more value

Power users are no longer limited by a lowest-common-denominator API.

Models are not the same - and that matters

Treating them as identical leads to misuse. Embracing differences leads to better outcomes.

Invalid configurations are caught early

Instead of runtime surprises, errors are surfaced immediately.

Better developer experience (DX)

Clear APIs, explicit capabilities, fewer hidden assumptions.

Most importantly: the library expresses domain knowledge correctly
The design now reflects reality - not an oversimplified version of it.

Looking Forward

We're not done yet.

We haven't fully committed the redesign - but we've started moving in this direction, and the changes will roll out in the next versions of Mozaik.

The goal is simple:

make model capabilities explicit
prevent invalid usage early
and let developers actually use the power of each model instead of hiding it

This is still evolving, and we'll likely learn more (and fix more mistakes) along the way.

But one thing is already clear:

We're no longer trying to hide the complexity of LLMs. We're designing for it.

Source:

Why a Single Interface for Multiple LLM Providers Is a Bad Design Decision

Why unified LLM abstractions fail and how modeling each LLM separately improves developer experience. A lesson in Domain-Driven Design.

jigjoy.ai

How to Build an Autonomous AI Agent That Executes Terminal Commands

Miodrag Vilotijević — Sun, 15 Mar 2026 18:54:33 +0000

What Makes an Agent Autonomous?

An autonomous agent is an agent that can make independent decisions to accomplish tasks-without constant human guidance.

But how do we measure the level of autonomy an agent has?

The answer lies in the variety of tasks an agent can perform on its own.

Consider an agent that has a single tool-the ability to write files. That's one degree of autonomy. It can create content, save it, and that's about it.

Now consider an agent with access to a terminal. Suddenly, the possibilities explode:

List files in any directory
Read and write files
Execute scripts and programs
Install packages
Interact with git repositories
Make network requests
And much more...

This is a high degree of autonomy-which, as we'll discuss, comes with both incredible power and important security considerations.

This is basically the idea behind modern coding tools like Claude Code—or even better, OpenClaw.

The Core Concept: Tool Execution Loop

The main thing we need to enable is an implementation for executing tools in a loop.

I'll use a library I built for this- @mozaik-ai/core - a TypeScript framework for orchestrating AI agents.

With Mozaik, we can easily equip an agent with tools. So we just need to create a terminal tool for executing commands.

Creating the Terminal Tool

First, let's define the terminal class that will give our agent the ability to execute shell commands:

import { spawn } from "child_process"

export class Terminal {

    runCommand(command: string, cwd: string): Promise<CommandResult> {
        return new Promise((resolve) => {
            const [cmd, ...args] = command.split(" ")
            const process = spawn(cmd, args, { cwd, shell: true })

            let stdout = "", stderr = ""

            process.stdout?.on("data", (data) => stdout += data.toString())
            process.stderr?.on("data", (data) => stderr += data.toString())

            process.on("close", (code) => {
                resolve({
                    success: code === 0,
                    stdout: stdout.trim(),
                    stderr: stderr.trim(),
                    exitCode: code ?? -1,
                })
            })
        })
    }
}

Now we define the tool that will give our agent the ability to execute shell commands:

The tool is straightforward: it takes a command string, executes it using Node.js's child_process module, and returns the output.

const terminal = new Terminal()
const tools: Tool[] = [
    {
        name: "run_command",
        description: "Run a command in the terminal.",
        schema: {
            type: "object",
            properties: {
                command: { type: "string", description: "The command to run in the terminal." },
                cwd: { type: "string", description: "The current working directory." },
            },
            required: ["command", "cwd"],
        },
        async invoke({ command, cwd }) {
            console.log(`Running command: ${command} in directory: ${cwd}`)
            console.log("--------------------------------")
            const result = await terminal.runCommand(command, cwd)
            return result
        },
    },
]

Attaching the Tool to an Agent

Now we attach the terminal tool to our agent:


agent.ts
const request: MozaikRequest = {
    model: "gpt-5-mini",
    tools: tools,
}
const userRequest = `Analyze the github respository and update the README.md file with a high level description of the project.`

const task = `You are a terminal agent. 

You can run commands in the terminal to help the user with their request. 
Do not ask any questions to the user. Just run the commands and return the result.

Tools:
- run_command: Run a command in the terminal. You can use this tool to run any command in the terminal.

User Request:
- ${userRequest}
`

const agent = new MozaikAgent(request)
const result = await agent.act(task)

Watching the Agent Work

Let's give the agent a task and watch it work. Below you can see what happens step by step - the terminal commands the agent autonomously executes to get the job done.

const userRequest = `Look at this folder and tell me in one sentence what it does 
                    — like you're explaining it to someone who has never written a line of code.`

The agent breaks it down on its own. It runs two commands to get the job done. The first command lists the files in the current directory, and the second command reads README.md to figure out the purpose of the project.

We can see which commands the agent executed to get the job done. No instructions on how to do it. Just the goal—and the agent figures out the rest.

Now, let's give the agent a more complex task:

const userRequest = `Analyze this directory and write 
                    a detailed description of the project 
                    in a file called purpose.md.`

We see the agent executed multiple commands to get the job done, and finally wrote the purpose.md file with the description of the project.

Security Considerations

With great autonomy comes great responsibility. Terminal access is powerful—but it can also be dangerous if not properly controlled.

The balance between autonomy and safety is a spectrum. Start with tighter controls and expand as you build confidence in your agent's behavior.

Final Thoughts

Building an autonomous agent with terminal access is surprisingly straightforward—the core pattern is just a tool execution loop.

What makes these agents powerful isn't the complexity of the implementation, but the emergent capabilities that arise from giving an LLM access to a shell.

The agent doesn't need to be explicitly programmed for every scenario. Give it a goal, give it tools, and it will find a way.

GitHub Repo:

Mijura / terminal-agent

A minimal AI-powered terminal agent that can execute shell commands and interact with the local system to automate tasks and workflows.

@mozaik-ai/terminal

A small terminal-agent project that lets an AI act as a terminal operator. It exposes a tool for running shell commands programmatically and returning structured results (stdout, stderr, exit code). The agent is built on top of Mozaik AI core primitives and is intended for automation tasks where an AI needs to inspect the repository, run commands, and modify files.

Key points

Project name: @mozaik-ai/terminal
Purpose: Provide a terminal tool that an AI agent can use to run commands in a shell and capture results.
Language: TypeScript (Node.js)
Entry point: src/index.ts

Features

Run arbitrary shell commands via a typed tool (run_command)
Captures stdout, stderr, and exit code
Simple Terminal class that spawns child processes and returns CommandResult objects

How it works (high level)

src/index.ts wires up a MozaikAgent with a single tool: run_command
The tool schema requires { command, cwd } and invokes Terminal.runCommand
Terminal.runCommand uses child_process.spawn (with shell…

View on GitHub

Source:

Building an Autonomous Agent That Can Run Terminal Commands

Learn how to build an autonomous AI agent with terminal access. Discover how tool-equipped agents can execute shell commands and accomplish complex tasks.

jigjoy.ai

DEV Community: JigJoy

Build Your Own CLI Agent: A Step-by-Step Guide

What we are building

How the pieces fit together

Step 1 — Bootstrap the runtime (cli.tsx)

Step 2 — Compose the session (session.ts)

Step 3 — The agent loop (terminal/agent.ts)

Step 4 — Tools the model can use (terminal/tools.ts)

Step 5 — Feed the terminal UI (ui-updater.ts)

Step 6 — Wire Ink (app.tsx)

Step 7 — Credentials and build

Starter repository

Where to go next

Learn more

Reactive Agents, Typed Event Handlers, and Agent Swarms: What's New in Mozaik

From Non-Blocking to Reactive

Typed Event Handlers

The Self vs. External Split

Plain Messages on the Bus

A Bigger Model Lineup

From One Agent to a Swarm

Composing Intelligence

Get started

Structured Context, Context Memory, Context Item Generators, and the Agentic Environment

Structured Context

Context Memory

Context Item Generators

Agentic Environment

Default Participants

A Foundation for Multi-Agent Systems

Why Agent Frameworks End Up As SDK Wrappers - And How To Overcome It

The Hidden Cost: Polluting Your Domain

Starting Point: OpenResponses

Client-created items

Model-generated items

Our Take on This

Enter Mozaik

Where This Leads

Basic Example

Final Thought

jigjoy-ai / mozaik

Mozaik is an open-source TypeScript framework for building event-driven AI agents.

Mozaik

Installation

API Key Configuration

The agentic environment

Non-blocking participants

Spektrum: Turn Natural Language into Live Web Apps (Deploy in Minutes with AI)

What Is Spektrum?

What You Can Do with Spektrum

Why This Matters (More Than You Think)

Key Features That Make Spektrum Different

Coding Agents in the Cloud

Real-Time Monitoring

From Idea to Production in Minutes

Flexible, Usage-Based Pricing

How Spektrum Works (From Prompt to Live App in a Few Lines)

Getting Started with Spektrum (Two Ways)

Option 1: Using the SDK (For Integration)

Option 2: Using the Spektrum Platform (What I Actually Used)

Step 1: Generate an API Key

Step 2: Create Your First Project

Step 3: Create Your First Task

Step 4: Generate and Deploy the App

My Experience: Building a Real App with Spektrum

Who Is Spektrum For?

A Small Note for the Community 💙

Final Thoughts

Hadil Ben AbdallahFollow

From Monolith to Microservices: How Bounded Context Improves AI-Driven Development

Introduction

Understanding Domain-Driven Design

The Monolith vs Microservices Debate

Why Monolithic Architectures Confuse AI Agents

What Is a Bounded Context?

Why Bounded Contexts Improve AI Development

Our Microservices Architecture

Avoiding the Big Ball of Mud

Final Thoughts

Why a Single Interface for Multiple LLM Providers Is a Bad Design Decision

Step 1 — Bootstrap the runtime (`cli.tsx`)

Step 2 — Compose the session (`session.ts`)

Step 3 — The agent loop (`terminal/agent.ts`)

Step 4 — Tools the model can use (`terminal/tools.ts`)

Step 5 — Feed the terminal UI (`ui-updater.ts`)

Step 6 — Wire Ink (`app.tsx`)