alice

Alice

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

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
• provides an alice delegate subcommand so OpenCode agents (including DeepSeek) can delegate subtasks to Codex, Claude, and other backends

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

Features

• Multi-bot runtime from a single config.yaml
• Per-bot isolated workspace, SOUL.md (in alice_home), and prompts, with shared CODEX_HOME by default
• Scene-aware routing for casual chat and explicit work threads
• Runtime HTTP API for bundled skills and automation
• Long-running LLM status cards with backend-activity and aggregated file-change signals
• Automation watchdog alerts for overdue or stuck scheduled tasks
• Bundled skills are materialized under ${ALICE_HOME:-~/.alice}/skills, linked into ~/.agents/skills, and exposed to Claude via ~/.claude/skills
• Embedded prompts, skills, config example, SOUL.md example, and OpenCode delegate plugin
• alice setup one-command init: config + skills + systemd unit + OpenCode plugin

Requirements

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

Quick Start

Install From Release

Via npm (recommended):

npm install -g @alice_space/alice
alice setup

Via installer script:

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. Start the service:

systemctl --user start alice.service   # Linux (alice setup writes the unit)
alice --feishu-websocket               # macOS / manual start

Run From Source

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

go mod tidy
go test ./...
go run ./cmd/connector --feishu-websocket

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: per-bot runtime directories
• codex_home: optional per-bot override for the shared CODEX_HOME (default: ~/.codex) Start from config.example.yaml.

Usage

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

• Usage Guide
• 使用说明

Delegating tasks to other LLM backends

The alice delegate subcommand runs a one-shot prompt against any configured LLM CLI:

alice delegate --provider codex --prompt "Refactor the auth module"
alice delegate --provider claude --prompt "Review this PR diff" < diff.patch

OpenCode plugin

alice setup writes the file ~/.config/opencode/plugins/alice-delegate.js. Once present, OpenCode agents (including DeepSeek) gain two tools — codex and claude — that delegate subtasks through the alice delegate command. No additional config is needed; OpenCode loads plugins from that directory automatically.

Additional docs:

• Documentation Index
• Architecture
• 架构文档

Connector startup mode is now explicit: use --feishu-websocket for the real Feishu connector, or --runtime-only for local runtime/API-only execution. For isolated debug or temporary rerun runtimes, use alice-headless --runtime-only; headless binaries no longer allow Feishu websocket startup.

The LLM backend abstraction lives in internal/llm/ (the former agentbridge library is now co-located in this repository).

SOUL.md

Each bot can define persona and machine-readable metadata in its configured soul_path. The default is <alice_home>/SOUL.md; a relative soul_path is resolved relative to <alice_home>.

Current frontmatter keys accepted by Alice:

• image_refs
• output_contract

The embedded example is prompts/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

When installing via npm, use alice setup after npm install -g @alice_space/alice to create the ALICE_HOME directory structure, write the initial config, sync bundled skills, register the systemd user unit (Linux), and install the OpenCode delegate plugin. The installer script is still available for users who prefer a single-curl workflow or need the release download / checksum verification path.

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