minimal-agent

A tiny, beautiful, composable, zero runtime deps multiagent terminal agent harness. Scale to hunders of parallel agents. See them chat and collab with together!

Comment

Inspiration

Most agent CLIs feel like black boxes. You install a binary, type a prompt, and hope the tool loop, provider wiring, auth, caching, and terminal renderer behave. When something breaks, you reverse-engineer a bundled app.

I wanted the opposite: a tiny, beautiful, composable agent harness where every moving part is a file you can read, a test you can run, and a debug path you can inspect. Built for people who care about the wire shape.

What it does

minimal-agent is a local terminal agent that:

  • Runs a real agent loop: interactive REPL, one-shot prompts, stdin, tool calls, streamed output, and session resume
  • Talks to any model through a provider-agnostic architecture. The loop, REPL, and renderers depend on canonical request/event types, never a vendor's wire format
  • Keeps the terminal sharp: live input, status rows, diffs, spinners, Markdown, and quit UX that are tested as terminal code
  • Makes internals inspectable: network captures, session JSONL, plugin manifests, config parsing, tool definitions

The host never imports a concrete plugin. Plugins never reach into host internals. Architecture fitness tests enforce that boundary on every CI run.

How I built it

  • Runtime: Bun only. Zero runtime npm dependencies by policy. TypeScript source runs directly, no build step
  • LLM layer: canonical request/events + capability schema + model registry. Provider plugins for OpenAI, Anthropic, OpenRouter, Ollama, OpenCode, generic OpenAI-compatible endpoints, and more
  • Plugin system: tools, TUIs, modes, live-area slots, slash commands, and schedule/cron all plug in through a thin host-owned registry
  • Sub-agents, intercom, computer use, Chrome CDP, memory, skills: first-class ports for multi-agent work and real machine control

Codex & GPT-5.6

This project was built and extended with Codex using GPT-5.6. Codex accelerated provider adapters, capability gating, architecture fitness tests, TUI edge cases, and the plugin boundary work. The harness is multi-provider and can talk to OpenAI models (including GPT-5.6) through the OpenAI provider plugin.

Challenges

  • Keeping zero runtime dependencies while still shipping a serious multi-provider agent
  • Making the canonical LLM layer coexist with a battle-tested legacy transport (timeouts, retries, 401 refresh) without a big-bang rewrite
  • Enforcing the host ↔ plugin boundary so layering cannot quietly rot
  • Building a terminal UX that feels alive without becoming untestable string soup

What I learned

Harness may be more important than models intelligence alone. You can get way better results by multi agent when you orchestrate agents correctly, minimal agent with its native intercom plugin makes all agents know, chat and collab with each other in realtime.

What's next

  • More provider plugins and surface codecs
  • Stronger mid-turn intercom preemption
  • Polished demo media for judges
  • Keep the host small, the plugins rich, and the wire shape honest

Try it

Mono Repository (private now): https://github.com/gastonmorixe/minimal-agent

git clone https://github.com/gastonmorixe/minimal-agent-core.git
cd minimal-agent-core
./minimal-agent login openai

Built With

  • agent
  • anthropic
  • bun
  • cli
  • codex
  • developer-tools
  • gpt-5.6
  • linux
  • llm
  • macos
  • openai
  • openrouter
  • plugins
  • terminal
  • typescript
  • zero-dependencies
Share this project:

Updates