AgentFlyer

Decentralized, cross-platform, multi-host federated AI Agent framework

AgentFlyer is an AI Agent runtime with multi-host federation, inspired by Openclaw. It introduces an in-process Agent Mesh, a token-efficient skill system, deep persistent memory, and decentralized multi-host federation as its core differentiator. The framework also integrates a task system and workflow system, aiming to give users rich and diverse control over AI agents. Let AI take flight!

Features

Core Features (F1–F12)

#	Feature	Description
F1	Config System	JSON5 format, multi-profile support, named model group registry (`group/model` reference style)
F2	Multi-LLM Support	Anthropic Claude, OpenAI GPT, Gemini, Ollama local models, OpenAI-compatible APIs (DeepSeek, etc.) via unified interface
F3	Token Metering	Exact counting + fast estimation, unified measurement across providers
F4	Messaging Channels	Telegram, Discord, Feishu (Lark), QQ, Web (with WebSocket real-time streaming)
F5	Agent Execution Engine	Tool-call loop, context compaction, subagent scheduling
F6	Session Persistence	JSONL format, per channel+key files, incremental append
F7	Skills System	SKILL.md-driven, injected on demand, minimal system prompt footprint
F8	Memory System	SQLite + BM25 full-text search + vector semantic search, partitioned by agent
F9	Cron Scheduler	Scheduled tasks with cron expressions and channel routing
F10	Workspace	Per-agent sandboxed file operations with path safety checks
F11	Console UI	Built-in web dashboard for realtime monitoring, config management, session viewing, workflow management
F12	CLI	`agentflyer gateway/agent/message/sessions/chat/config/skills/memory/federation` command set

Enhanced Features (E1–E8)

#	Feature	Description
E1	Agent Mesh	Agents within the same instance can discover and delegate tasks to each other, breaking the hierarchy constraint
E2	Collaborative Skills	Cross-agent capability labels, on-demand composition
E3	Federated Memory	Memory sync across instances, importance decay, vector search
E4	Decentralized Federation	Ed25519 identity, AES-GCM encrypted communication, multiple discovery modes
E5	PoTC Proof of Work	Token consumption proof + FlyCredit compute exchange
E6	Remote Task Routing	Automatically routes to federated nodes when local agent capabilities are insufficient
E7	Dual Ledger	Local ledger + peer reconciliation to prevent fraud
E8	User Authorization Control	Federation network participation requires explicit user opt-in

Architecture

+-------------------------------------------------------------+
|                    AgentFlyer Instance                       |
|                                                             |
|  +----------+  +----------+  +----------+  +-----------+  |
|  | Telegram |  |  Feishu  |  | Discord  |  |  Console  |  |
|  | Channel  |  | Channel  |  | Channel  |  |    UI     |  |
|  +----+-----+  +----+-----+  +----+-----+  +-----+-----+  |
|       +---------------+---------------+-----------+        |
|                           |                                 |
|  +------------------------v-------------------------------+ |
|  |              Message Router / Session Key              | |
|  +------------------------+-------------------------------+ |
|                           |                                 |
|  +------------------------v-------------------------------+ |
|  |                 Mesh Bus (in-memory)                   | |
|  |                                                        | |
|  |   +----------+  +----------+  +--------------------+  | |
|  |   |  main    |<->| worker  |  |     specialist     |  | |
|  |   | (coord.) |  |(worker) |  |   (domain expert)  |  | |
|  |   +----+-----+  +----------+  +--------------------+  | |
|  +--------+-----------------------------------------------+ |
|           |                                                  |
|  +--------v------------------------------------------------+ |
|  |         Core Services                                   | |
|  |  Memory(SQLite+Vec) | Skills | Scheduler | Config       | |
|  +---------------------------------------------------------+ |
|                                                             |
|  +---------------------------------------------------------+ |
|  |   Federation Layer (optional)                          | |
|  |  Ed25519 Identity | WS Transport | mDNS/Tailscale/Static| |
|  +----------------------------+----------------------------+ |
+----------------------------+--------------------------------+
                             | Cross-host federation
           +-----------------+-----------------+
           v                                   v
   [Other AgentFlyer Instance]       [Other AgentFlyer Instance]

Startup Sequence

config.load() -> memory.init() -> channels.start() -> HTTP+WS.listen()
  -> agents.restore() -> scheduler.start() -> federation.connect()

Quick Start

Install via npm (Recommended)

# Install globally
npm install -g agentflyer

# Or use directly without installing
npx agentflyer --help

Run

# Start the gateway
agentflyer start

# Interactive CLI chat
agentflyer chat

On first run, a minimal config is auto-generated at ~/.agentflyer/agentflyer.json. Open http://localhost:19789 to enter the Console UI for visual configuration.

Build from Source

Prerequisites for source build:

Bun >= 1.2 (recommended) or Node.js >= 22
pnpm >= 9

git clone https://github.com/tddt/AgentFlyer.git
cd AgentFlyer
pnpm install
pnpm build

# Development mode (Bun, no build required)
pnpm dev start

# Interactive CLI chat
agentflyer chat

Configuration Reference

The config file lives at ~/.agentflyer/agentflyer.json in JSON5 format.

{
  "version": 2,

  // Gateway service config
  "gateway": {
    "bind": "loopback",      // loopback | local | tailscale
    "port": 19789,
    "auth": { "mode": "token", "token": "your-token" }
  },

  // Named model groups (agents reference models as "groupName/modelName", e.g. "deepseek/chat")
  "models": {
    "deepseek": {
      "provider": "openai-compat",
      "apiBaseUrl": "https://api.deepseek.com/v1",
      "apiKey": "sk-...",
      "models": {
        "chat": { "id": "deepseek-chat", "maxTokens": 8192 }
      }
    },
    "claude": {
      "provider": "anthropic",
      "apiKey": "sk-ant-...",
      "models": {
        "haiku": { "id": "claude-haiku-3-5", "maxTokens": 8192 },
        "opus":  { "id": "claude-opus-4-5",  "maxTokens": 8192 }
      }
    },
    "local": {
      "provider": "ollama",
      "apiBaseUrl": "http://localhost:11434",
      "models": {
        "qwen": { "id": "qwen2.5:7b", "maxTokens": 4096 }
      }
    }
  },

  // Global defaults
  "defaults": {
    "model": "deepseek/chat",   // format: groupName/modelName
    "maxTokens": 8192,
    "workspace": "~/.agentflyer/workspace"
  },

  // Agent list
  "agents": [
    {
      "id": "main",
      "name": "Main Assistant",
      "model": "deepseek/chat",   // overrides global default
      "skills": ["base", "file-ops", "web-search"],
      "workspace": "/path/to/workspace",
      "mesh": {
        "role": "coordinator",
        "capabilities": ["orchestration", "user-interface"],
        "accepts": ["task", "query", "notification"],
        "visibility": "public"
      },
      "tools": {
        "deny": [],
        "approval": ["bash", "read_file"]   // tools requiring user approval
      },
      "persona": {
        "language": "en-US",
        "outputDir": "output"
      }
    }
  ],

  // Channel config (see "Messaging Channels" section)
  "channels": {
    "defaults": {
      "output": "logs",           // default output channel
      "schedulerOutput": "logs"   // scheduler task output channel
    },
    "cli":      { "enabled": true },
    "web":      { "enabled": true },
    "telegram": { "enabled": false, "botToken": "" },
    "discord":  { "enabled": false, "botToken": "" },
    "feishu":   { "enabled": false, "appId": "", "appSecret": "" },
    "qq":       { "enabled": false, "appId": "", "clientSecret": "" }
  },

  // Federation config (optional, see "Federation" section)
  "federation": {
    "enabled": false,
    "peers": [],
    "discovery": { "mdns": true, "tailscale": false, "static": true }
  }
}

Supported LLM Providers

Provider	Example Models	Notes
`anthropic`	claude-haiku-3-5, claude-opus-4-5	Requires `apiKey`
`openai`	gpt-4o, gpt-4o-mini	Requires `apiKey`
`google`	gemini-1.5-pro	Requires `apiKey`
`ollama`	qwen2.5:7b, llama3.2	Local runtime, set `apiBaseUrl`
`openai-compat`	deepseek-chat, other compatible models	Set `apiBaseUrl` + `apiKey`

Messaging Channels

Telegram

"telegram": {
  "enabled": true,
  "botToken": "YOUR_BOT_TOKEN",
  "defaultAgentId": "main",
  "allowedChatIds": [],      // empty = no restriction
  "pollIntervalMs": 2000
}

Discord

"discord": {
  "enabled": true,
  "botToken": "YOUR_BOT_TOKEN",
  "defaultAgentId": "main",
  "allowedChannelIds": [],
  "commandPrefix": "!agent"
}

Feishu (Lark)

After creating an app on the Feishu Open Platform, set the event subscription URL to: https://your-gateway/channels/feishu/event

"feishu": {
  "enabled": true,
  "appId": "cli_xxxxxxxx",
  "appSecret": "your-app-secret",
  "verificationToken": "",     // Feishu event verification token (optional)
  "encryptKey": "",            // Feishu message encryption key (optional)
  "defaultAgentId": "main",
  "allowedChatIds": [],        // empty = no restriction
  "agentMappings": {           // Feishu group name/user nickname -> agent ID mapping
    "Main Control": "main",
    "Worker One": "worker-1"
  }
}

QQ

"qq": {
  "enabled": true,
  "appId": "YOUR_APP_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "defaultAgentId": "main",
  "allowedGroupIds": []
}

Web (built-in)

Visit http://localhost:19789 to open the Console UI and use the built-in Chat tab for real-time conversation with WebSocket streaming.

Agent Mesh

AgentFlyer supports multiple agents within the same instance discovering and collaborating with each other, breaking the constraint of tree-structured subagents.

Roles

Role	Behavior
`coordinator`	Task assignment and result aggregation; can discover/schedule other agents
`worker`	Accepts tasks, executes, and reports results
`specialist`	Has domain-specific capabilities; discoverable by capability label
`observer`	Read-only; listens to the message stream

Available Tools

The following Mesh tools are automatically injected at agent runtime:

// Discover agents with a specific capability
mesh_discover({ capability: 'finance-analysis' })

// Delegate a task to a specific agent
mesh_delegate({
  to: 'analyst',
  task: 'Analyze today trend for stock XYZ',
  timeout: 30000,
  expectsStructuredResult: true
})

// Broadcast a message to all agents
mesh_broadcast({ topic: 'market-alert', payload: { ... } })

Federation

Multiple AgentFlyer instances across different hosts can form a federated network, delegating tasks to each other and sharing compute.

Enable Federation

"federation": {
  "enabled": true,
  "peers": [],
  "discovery": {
    "mdns": true,       // LAN auto-discovery
    "tailscale": false, // Tailscale network discovery
    "static": true      // Manual peer config (in peers array)
  },
  "economy": {
    "mode": "invite-only",
    "earn": { "maxDaily": 100, "maxPerTask": 20 },
    "spend": { "maxDaily": 200, "minBalance": 10 }
  }
}

PoTC (Proof of Token Consumption)

When a local node executes a task for a remote node, it generates a WorkReceipt containing:

The model used and token consumption (inputTokens / outputTokens)
SHA-256 hash of the task result
Ed25519 signature of the executing node

After verifying the receipt, the receiver updates the local FlyCredit (FC) ledger. FC is used only for internal compute exchange within the network and cannot be transferred externally.

Memory System

AgentFlyer uses SQLite to store memory entries, supporting BM25 full-text search and vector semantic search.

~/.agentflyer/
  memory/
    memories.db       # main memory database
    vec_index.bin     # vector index (sqlite-vec)

Partitions

Memory is isolated by partition, defaulting to agent ID:

// Memory tools available to agents
memory_store({ content: 'User prefers dark mode', importance: 0.8 })
memory_search({ query: 'user interface preferences', limit: 5 })
memory_recall({ id: 'mem_01J...' })
memory_forget({ id: 'mem_01J...' })

Memory Configuration

"memory": {
  "enabled": true,
  "embed": {
    "provider": "local",
    "model": "Xenova/all-MiniLM-L6-v2"   // local vector embedding, no API needed
  },
  "decay": {
    "enabled": true,
    "halfLifeDays": 30   // memory importance half-life
  },
  "maxEntries": 10000
}

Skills System

Skills are capability units for AgentFlyer, described by SKILL.md files and injected into the system prompt on demand.

Skills Directory Configuration

"skills": {
  "dirs": [
    "/path/to/custom-skills",   // user-defined skills directory
    "~/.agentflyer/skills"
  ],
  "compact": true,              // compress skill descriptions to save tokens
  "summaryLength": 60           // max skill summary length
}

SKILL.md Format

---
name: web-search
description: Search the web for the latest information
tools: [search_web, fetch_page]
tokens: 120
trigger: auto
keywords: [search, query, latest]
---

## Role
You can use the following tools to perform web searches...

Console UI

Built-in web dashboard at http://localhost:19789 (Bearer Token authentication required).

Tabs

Tab	Function
Overview	System status: runtime info, channel status, active session count
Agents	Agent list and details, realtime message stream
Chat	Real-time chat with any agent, WebSocket streaming
Logs	Live log stream with level filtering
Config	Visual config editor (Gateway, Models, Agents, Channels, Memory, etc.)
Scheduler	Cron task management: create, edit, view execution history
Sessions	Session history list and message replay
Workflow	Workflow definition and execution management
Memory	Memory entry search, view, and management
Federation	Federated peer status, peer connection management
Guide	Project usage guide (this document)
About	Runtime version and license info

CLI Commands

# -- Gateway management -----------------------------------------------
agentflyer start [--port 19789] [--bind loopback]
agentflyer gateway stop
agentflyer gateway status

# -- Agent management -------------------------------------------------
agentflyer agent list
agentflyer agent reload [--id <agentId>]

# -- Send messages ----------------------------------------------------
agentflyer message send --agent <id> --message "Hello"

# -- Session management -----------------------------------------------
agentflyer sessions list [--agent <id>]
agentflyer sessions show <sessionKey>
agentflyer sessions clear <sessionKey>

# -- Interactive chat -------------------------------------------------
agentflyer chat [--agent main]

# -- Config management ------------------------------------------------
agentflyer config show
agentflyer config set <key> <value>
agentflyer config edit         # open system editor

# -- Skills management ------------------------------------------------
agentflyer skills list

# -- Memory management ------------------------------------------------
agentflyer memory search <query>
agentflyer memory list [--agent <id>] [--limit 20]
agentflyer memory delete <id>

# -- Federation management --------------------------------------------
agentflyer federation status
agentflyer federation peers
agentflyer federation trust <nodeId>

# -- Shortcuts --------------------------------------------------------
agentflyer reload     # alias for agent reload
agentflyer web        # open Console UI in browser

Directory Structure

agentflyer/
+-- src/
|   +-- core/          # base runtime (no framework dependencies)
|   |   +-- config/    # config management (zod schema + JSON5 parsing)
|   |   +-- runtime/   # Bun/Node compatibility layer
|   |   +-- session/   # session persistence (JSONL)
|   |   +-- types/     # core type definitions
|   +-- agent/         # Agent execution engine
|   |   +-- runner/    # LLM call wrappers (unified interface)
|   |   +-- prompt/    # System Prompt assembly
|   |   +-- compactor/ # context compaction (token budget management)
|   |   +-- tools/     # tool registration + call execution
|   +-- skills/        # skills system
|   +-- memory/        # memory storage (SQLite + BM25 + Vec)
|   +-- mesh/          # Agent Mesh (in-process message bus)
|   +-- federation/    # cross-host federation
|   |   +-- transport/ # WebSocket transport layer
|   |   +-- discovery/ # mDNS / Tailscale / Static
|   |   +-- ledger/    # FC ledger + PoTC proof
|   +-- channels/      # messaging channel adapters
|   |   +-- telegram/
|   |   +-- discord/
|   |   +-- feishu/
|   |   +-- web/
|   +-- gateway/       # HTTP + WS entry point
|   |   +-- server.ts  # server startup
|   |   +-- rpc.ts     # RPC interface (used by Console UI)
|   |   +-- console-ui/# React dashboard frontend
|   +-- scheduler/     # Cron scheduler
|   +-- cli/           # CLI entry point
+-- tests/
|   +-- unit/
|   +-- integration/
|   +-- e2e/
+-- docs/              # internal design docs (not user docs)
+-- package.json
+-- pnpm-workspace.yaml
+-- tsconfig.json

Runtime Data Directory

~/.agentflyer/
+-- agentflyer.json        # main config file
+-- credentials/           # encrypted API keys (AES-256-GCM)
+-- sessions/              # session logs (JSONL)
+-- memory/                # memory database
+-- workspace/             # agent default workspace
+-- skills/                # user-defined skills

Development Guide

Setup

pnpm install

Development Commands

# Type checking
pnpm typecheck

# Code quality check
pnpm check

# Auto-fix formatting
pnpm check:fix

# Run tests
pnpm test

# Coverage report
pnpm test:coverage

# Build output
pnpm build

Module Dependency Direction

core/ <- skills/ <- agent/ <- mesh/ <- federation/
core/ <- memory/
core/ <- channels/
(all of the above) <- gateway/ <- cli/

Lower-level modules must not depend on higher-level modules.

Technology Stack

Layer	Choice
Runtime	Bun >= 1.2 (Node.js >= 22 compatible)
Language	TypeScript 5.x (strict ESM)
Config validation	zod@3 + json5@2
LLM	@anthropic-ai/sdk + openai@4
Memory storage	SQLite (better-sqlite3) + sqlite-vec + BM25
CLI	citty + @clack/prompts
Federation crypto	@noble/ed25519 + @noble/ciphers
Testing	Vitest + msw@2 (Mock LLM)

Commit Convention

feat(core): add new feature
fix(agent): fix issue
refactor(memory): refactor module
test(channels): add tests
docs(readme): update documentation
chore(deps): dependency updates

Before committing, all of the following must pass:

pnpm typecheck && pnpm check && pnpm test

License

MIT License — see LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
scripts		scripts
src		src
tests/unit		tests/unit
.gitignore		.gitignore
.nvmrc		.nvmrc
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
README_CN.md		README_CN.md
biome.json		biome.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

AgentFlyer

Table of Contents

Features

Core Features (F1–F12)

Enhanced Features (E1–E8)

Architecture

Startup Sequence

Quick Start

Install via npm (Recommended)

Run

Build from Source

Configuration Reference

Supported LLM Providers

Messaging Channels

Telegram

Discord

Feishu (Lark)

QQ

Web (built-in)

Agent Mesh

Roles

Available Tools

Federation

Enable Federation

PoTC (Proof of Token Consumption)

Memory System

Partitions

Memory Configuration

Skills System

Skills Directory Configuration

SKILL.md Format

Console UI

Tabs

CLI Commands

Directory Structure

Runtime Data Directory

Development Guide

Setup

Development Commands

Module Dependency Direction

Technology Stack

Commit Convention

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages