English | 简体中文

octobot is a modular AI agent framework built in TypeScript. It focuses on multi-channel interaction, session and memory management, skill expansion, and tool orchestration for engineering workflows. Inspired by nanobot.

• Multi-LLM support (OpenAI, Anthropic, VolcEngine, DeepSeek, Gemini, Zhipu, Moonshot, and more)
• Multi-channel access (CLI and Feishu bot)
• Dual memory model (MEMORY.md + HISTORY.md)
• Skill system based on SKILL.md with dependency checks and on-demand loading
• MCP integration for Model Context Protocol servers
• Message bus architecture for decoupled channels and core loop
• Tooling for files, shell, web search/fetch, subagents, and cron
• JSONL session persistence with multi-session support

npm i -g octobot

git clone https://github.com/yourusername/octobot.git
cd octobot
npm install
npm run build
npm link

octobot onboard

Config file: ~/.octobot/config.json

{
  "agents": {
    "defaults": {
      "workspace": "~/.octobot/workspace",
      "model": "ark-code-latest",
      "provider": "volcengine",
      "max_tokens": 8192,
      "temperature": 0.1,
      "max_tool_iterations": 40,
      "memory_window": 100
    }
  },
  "providers": {
    "volcengine": {
      "api_key": "YOUR_API_KEY",
      "api_base": "https://ark.cn-beijing.volces.com/api/coding/v3"
    }
  },
  "tools": {
    "web": {
      "search": {
        "api_key": "TAVILY_API_KEY",
        "max_results": 5
      }
    },
    "exec": {
      "timeout": 60,
      "path_append": ""
    },
    "restrict_to_workspace": false
  },
  "channels": {
    "feishu": {
      "enabled": false,
      "app_id": "",
      "app_secret": ""
    }
  }
}

# Start interactive CLI chat
octobot agent

# Start Feishu gateway (requires channels.feishu config)
octobot gateway

# Show current provider/model and examples
/model

# Switch provider + model
/model openai gpt-4o-mini
/model anthropic/claude-3.5-sonnet

Notes:

• Use provider/model format when switching; the client will reconfigure baseURL if needed.
• Suggestions depend on current provider and account availability.

› hello
octobot: Hello! How can I help?

1. Create a bot in Feishu Open Platform
2. Configure channels.feishu.app_id and channels.feishu.app_secret
3. Run octobot gateway
4. Mention the bot in Feishu to start a conversation

• JSON 2.0 unified: all cards use schema: "2.0" with body.elements
• Markdown: headings (bold), quotes (>), lists (-/*/1.), links (text), fenced code (```)
• Table: markdown tables converted to 2.0 table component; link cells auto-use lark_md
• Toggle tool hints in replies with channels.send_tool_hints (default false).
• To send media (images/files/audio), include file paths in outbound metadata: media: ["/path/to.png"].

Example (table in 2.0):

{
  "schema": "2.0",
  "body": {
    "elements": [
      {
        "tag": "table",
        "page_size": 5,
        "columns": [
          { "name": "rank", "display_name": "#", "data_type": "number" },
          { "name": "title", "display_name": "Title", "data_type": "lark_md" },
          { "name": "summary", "display_name": "Summary", "data_type": "text" },
          { "name": "link", "display_name": "Link", "data_type": "lark_md" }
        ],
        "rows": [
          {
            "rank": 1,
            "title": "**OpenAI 发布 GPT-5.4**",
            "summary": "OpenAI 推出 GPT-5.4 …",
            "link": "[OpenAI官方](https://openai.com)"
          }
        ]
      }
    ]
  }
}

Skills live at {workspace}/skills/<skill>/SKILL.md and use frontmatter + markdown.

---
name: tmux
description: Control tmux sessions
always: false
metadata: {"octobot": {"requires": {"bins": ["tmux"]}}}
---

# tmux Skill
Use tmux to manage terminal sessions...

• Channels: CLI / Feishu
• Core: AgentLoop + MessageBus
• Managers: Session / Memory / Skills
• Infra: LLM Provider / Tools / Config

flowchart TB
  subgraph channels[Channels]
    CLI[CLI Channel]
    Feishu[Feishu Channel]
  end

  subgraph core[Core]
    Bus[MessageBus]
    Loop[AgentLoop]
    Context[ContextBuilder]
  end

  subgraph managers[Managers]
    Sessions[SessionManager]
    Memory[MemoryManager]
    Skills[SkillManager]
  end

  subgraph infra[Infra]
    LLM[LLM Provider]
    Tools[Tool Registry]
    MCP[MCP Connector]
    Config[Config Loader]
  end

  CLI --> Bus
  Feishu --> Bus
  Bus --> Loop
  Loop --> Context
  Loop --> Tools
  Loop --> Sessions
  Loop --> Memory
  Loop --> Skills
  Loop --> LLM
  Tools --> MCP
  Config --> Loop

sequenceDiagram
  participant User
  participant Channel
  participant Bus
  participant AgentLoop as Agent
  participant Context
  participant LLM
  participant Tools

  User->>Channel: Message
  Channel->>Bus: InboundMessage
  Bus->>Agent: consumeInbound()
  Agent->>Context: buildMessages()
  Context-->>Agent: system + history + user
  Agent->>LLM: chat()
  LLM-->>Agent: response / tool_calls
  Agent->>Tools: execute tools
  Tools-->>Agent: tool results
  Agent->>LLM: follow-up
  Agent-->>Bus: OutboundMessage
  Bus-->>Channel: publishOutbound()
  Channel-->>User: Reply

flowchart TD
  Build[buildSystemPrompt] --> Always[Always Skills Content]
  Build --> Summary[Skills Summary]
  Always --> Cache[SkillManager cache]
  Summary --> Scan[SkillLoader listSkills]
  Scan --> Workspace[Workspace skills]
  Scan --> Builtin[Builtin skills]
  Summary --> Read[read_file on demand]

{
  "mcp": {
    "enabled": true,
    "servers": {
      "sqlite": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-sqlite", "./data.db"]
      }
    }
  }
}

MCP servers: https://github.com/modelcontextprotocol/servers

npm run dev
npm run dev:gateway

dev and dev:gateway watch src and restart on changes.

# Build then publish as a public package
npm run release

# Dry run: create tarball to inspect package contents
npm run release:dry

# Pre-publish hook (runs automatically before publish)
npm run prepublishOnly

# Version helpers (also creates a commit with message)
npm run version:patch  # 0.0.1 bump
npm run version:minor  # 0.1.0 bump
npm run version:major  # 1.0.0 bump

• Run TypeScript checks: npx tsc --noEmit
• Follow existing code style
• Update docs for functional changes

MIT

• Inspired by nanobot
• Feishu SDK: @larksuiteoapi/node-sdk