alice

Alice

A Feishu long-connection connector for CLI-based LLM agents such as Codex, Claude, Gemini, and Kimi.

Alice runs as a local multi-bot runtime:

• receives Feishu messages over WebSocket
• routes messages into chat or work scenes
• calls the configured LLM CLI backend
• sends progress, replies, files, and images back to Feishu
• exposes a local runtime API used by bundled skills

For Chinese documentation, see README.zh-CN.md.

Features

• Multi-bot runtime from a single config.yaml
• Per-bot isolated workspace, SOUL.md, prompts, and CODEX_HOME
• Scene-aware routing for casual chat and explicit work threads
• Runtime HTTP API for bundled skills and automation
• Embedded prompts, skills, config example, and SOUL.md example
• Release installer for systemd --user deployments

Requirements

• Go 1.25+ for source builds
• One installed and authenticated backend CLI:
  • codex
  • claude
  • gemini
  • kimi
• A Feishu app with:
  • bot capability
  • im.message.receive_v1 subscription
  • required message permissions
  • long connection mode enabled

Quick Start

Install From Release

curl -fsSL https://cdn.jsdelivr.net/gh/Alice-space/alice@main/scripts/alice-installer.sh | bash -s -- install

Then:

1. Edit ${ALICE_HOME:-~/.alice}/config.yaml
2. Set bots.*.feishu_app_id and bots.*.feishu_app_secret
3. Restart the service:

systemctl --user restart alice.service

Run From Source

cp config.example.yaml ~/.alice/config.yaml
# edit ~/.alice/config.yaml

go mod tidy
go test ./...
go run ./cmd/connector

Configuration

Alice uses a pure multi-bot config model.

Important concepts:

• bots.<id>: one runtime bot
• llm_profiles: named model presets
• group_scenes.chat: conversational scene for group chats
• group_scenes.work: explicit task scene for work threads
• trigger_mode: legacy fallback when both scenes are disabled
• workspace_dir / prompt_dir / codex_home: per-bot runtime directories
• image_generation: optional roleplay image generation pipeline

Start from config.example.yaml.

Usage

Alice's operating model and chat / work scene behavior are documented in:

• Usage Guide
• 使用说明

Additional docs:

• Architecture
• 架构文档
• Feishu Message Flow (Chinese)

SOUL.md

Each bot can define persona and machine-readable metadata in workspace/SOUL.md.

Current frontmatter keys accepted by Alice:

• image_refs
• image_generation
• output_contract

The embedded example is SOUL.md.example.

Installer

The installer script lives at scripts/alice-installer.sh.

Common commands:

# install or update the latest stable release
curl -fsSL https://cdn.jsdelivr.net/gh/Alice-space/alice@main/scripts/alice-installer.sh | bash -s -- install

# uninstall
curl -fsSL https://cdn.jsdelivr.net/gh/Alice-space/alice@main/scripts/alice-installer.sh | bash -s -- uninstall

Development

make check
make build
make run

make check includes formatting, vet, unit tests, and connector race tests.

Contribution guidelines are in CONTRIBUTING.md.

Release Process

• Day-to-day work happens on dev
• dev -> main drives the normal release path
• Tagged releases are published through GitHub Actions

Workflow files:

• .github/workflows/ci.yml
• .github/workflows/main-release.yml
• .github/workflows/release-on-tag.yml

License

MIT