# Add to your Claude Code skills
git clone https://github.com/meetopenbot/openbotOpenBot is a local-first harness for running AI agents. It is built around a small event API, local file storage, and a Melony-powered runtime that routes events to agents and plugins.
~/.openbot.system agent named Lolly.~/.openbot/agents/<agent-id>/AGENT.md.~/.openbot/plugins.Requires Node.js >=20.12.0.
npm i -g openbot
openbot start
The server listens on http://localhost:4132 by default. Set a different port with:
openbot start --port 3000
For local development:
npm install
npm run dev
OpenBot intentionally keeps the public API small:
GET /api/events opens an SSE stream for a channel or thread.POST /api/publish publishes an event into the harness.GET /api/state runs an event and returns the resulting events without opening a stream.Example:
curl -X POST http://localhost:4132/api/publish \
-H "content-type: application/json" \
-d '{"type":"user:input","data":{"content":"hello"}}'
Useful context can be passed as headers, query params, or body fields:
No comments yet. Be the first to share your thoughts!
channelIdthreadIdagentIdrunIdOpenBot reads config from ~/.openbot/config.json.
{
"port": 4132,
"baseDir": "~/.openbot",
"model": "openai/gpt-4o-mini",
"mcpServers": []
}
Variables are read from ~/.openbot/variables.json and applied to the server process environment on startup.
The built-in system agent is always available. Add a custom agent by creating ~/.openbot/agents/<agent-id>/AGENT.md:
---
name: Researcher
description: Helps collect and summarize information.
runtime:
name: ai-sdk
config:
model: openai/gpt-4o-mini
plugins:
- name: storage
---
You are a careful research assistant.
Summarize findings clearly and cite sources when available.
Agents are discovered from disk when the server starts.
Built-in plugins include:
storagedelegationmcpuiai-sdkShared plugins can be placed in ~/.openbot/plugins and referenced by agents.
src/app: CLI, server, event types, and app config.src/harness: agent harness, orchestration, process, and MCP runtime helpers.src/plugins: built-in plugin implementations.src/services: local storage service.src/registry: plugin registry.docs: architecture, agents, and plugin notes.Need help or want to share feedback? Join the community on Discord: https://discord.gg/XYYXvN2ebB