QUICKSTART

Build your first Modu agent

Install Modu, register an LLM provider, and run your first prompt. The shortest path takes about five minutes.

Modu requires Go 1.26.2 or later. Treat the repository’s go.mod as the source of truth.

1. Install

Add Modu to your Go project:

terminal

$ go get github.com/openmodu/modu

2. Build your first agent

Register an OpenAI-compatible endpoint, create a model and agent, then call Prompt. This follows the structure of the repository’s agent_demo.

main.go

package main

import (
  "context"
  "github.com/openmodu/modu/pkg/agent"
  "github.com/openmodu/modu/pkg/providers"
  "github.com/openmodu/modu/pkg/providers/openai"
  "github.com/openmodu/modu/pkg/types"
)

func main() {
  providers.Register(openai.New(
    "ollama",
    openai.WithBaseURL("http://localhost:11434/v1"),
  ))

  model := &types.Model{
    ID: "llama3.2", Name: "Llama 3.2", ProviderID: "ollama",
  }
  a := agent.NewAgent(types.Config{
    InitialState: &types.State{
      SystemPrompt: "You are helpful.",
      Model: model,
    },
  })

  _ = a.Prompt(context.Background(), "Explain Modu in three sentences")
}

3. Run examples

The repository examples are the shortest integration tests. Start with the path closest to your goal:

terminal

# Basic agent and tool calls
go run ./examples/agent_demo

# Checkpoints, recovery, and rollback
go run ./examples/runtime_demo

# Multi-agent coordination
go run ./examples/agent_teams

AGENT RUNTIME

Agent loop and ownership boundaries

pkg/agent owns the ReAct-style execution loop, tool calls, queues, events, and interruption. Your application still owns prompts, the tool catalog, persistence policy, and deployment.

Prompt User input

Agent Loop Plan and act

Tools Real actions

Events Observable output

Checkpoints and session recovery

pkg/runtime records a checkpoint after every committed message. After a restart, you can continue an unfinished session or restore an earlier checkpoint as a new branch head.

runtime.go

store, err := runtime.NewFileStore("./checkpoints")
rt := runtime.New(agent.NewAgent(cfg), store, "session-123")

err = rt.Run(ctx, "do the thing")
resumed, err := rt.Resume(ctx)

Events and state

Use Subscribe to receive Agent, Turn, Message, and Tool Execution events. Subscribers can drive logs, a TUI, metrics, or synchronization with external state.

CODING AGENT

A complete terminal coding workflow

pkg/coding_agent adds sessions, context compaction, skills, approvals, and code-oriented tools on top of the agent kernel. To try the full TUI:

terminal

$ go run ./cmd/modu_code

Tools and skills

Tools implement the shared types.Tool contract. Skills inject reusable workflows through SKILL.md. Host applications can select only the capabilities they need.

MULTI-AGENT

Mailbox Teams

Mailbox provides agent registration, independent inboxes, task and project state, capability queues, result validation, pipelines, and conversation records. It coordinates agents without calling an LLM.

HubRoutes messages and maintains agent, task, and project state

ClientRegisters across processes, sends messages, and claims tasks

SQLite StoreRecovers coordination state across restarts

DashboardShows tasks, states, and conversation history

Coordination architecture

Agent Teams suits work split by a coordinator and executed by multiple workers. Adversarial Validation suits queues where results require independent acceptance. Both use the Mailbox task model.

Coding Agent architecturePackages, dependency direction, and execution path Mailbox Agent SystemProtocol, persistence, and failure scenarios Complete documentation indexGuides, references, architecture, and articles