Feishu Agent Console

Feishu Agent Console is a personal remote coding console for running Codex-based agents from Feishu or Lark chat.

You send commands such as /task, /status, /queue, /tail, and /correct in Feishu. A Node.js service on your server queues tasks, runs Codex against configured Git repositories, executes real verification commands, updates Feishu cards, and writes full command evidence to Markdown logs.

The project is intentionally small: it is not a multi-tenant platform, approval system, or web dashboard. It is a practical single-user backend for letting an agent work on your own repositories while you control it from chat.

Features

• Feishu/Lark bot over persistent WebSocket events.
• Task queue with one active task at a time.
• Interactive Feishu cards for task status, queue, logs, stop, and correction actions.
• Session commands for starting a new chat, listing sessions, opening old sessions, and viewing history.
• Project registry with named projects and direct --dir repository selection.
• Codex runtime for codex-gsd projects and an official BMAD wrapper for bmad-official projects.
• BMAD Commander mode: a thin Feishu-side administrator prompt that drives official BMAD skills automatically while preserving direct BMAD interaction when requested.
• Evidence Runner that executes real test, build, diff, status, and Docker commands.
• Auto-repair loop: failed verification output is fed back to Codex up to maxRepairRounds.
• Markdown log files containing prompts, stdout, stderr, exit codes, and diffs.
• Native Feishu file/image intake for task context.

Architecture

Feishu / Lark Bot
  -> FeishuClient
  -> Command Parser
  -> SQLite Task Queue
  -> TaskRunner
  -> CodexGsdRuntime
  -> EvidenceRunner
  -> Markdown Logs + Feishu Card Updates

Codex edits the repository. Evidence Runner decides whether the work is actually valid by running your configured commands. The bot only summarizes state; full evidence stays on disk.

Supported Project Runtimes

This repository currently supports two Codex-backed project modes:

Runtime	Purpose	Typical use
codex-gsd	Codex with GSD-style workflow prompts	General coding tasks, lightweight plan/implement/verify work
bmad-official	Feishu wrapper over official BMAD-METHOD installed Codex skills	True BMAD interaction from Feishu
bmad-codex	Compatibility mode: one Codex call with BMAD Method prompts	Existing simple deployments
bmad-multi	Experimental local orchestrator	Not recommended when official BMAD-METHOD is available

All runtimes use the same queue, Feishu cards, Markdown logs, and project registry. For true BMAD usage, prefer bmad-official: the target repository must have official BMAD-METHOD installed for Codex (_bmad/ plus .agents/skills/bmad-*). Feishu only sends messages into a persistent Codex session and displays the official BMAD reply.

bmad-official supports two interaction styles:

• BMAD Commander: default for /task, /new, /auto, and normal follow-up text in a BMAD session. The Feishu-side administrator prompt calls official BMAD skills, auto-continues low-risk A/P/C style choices, writes outputs to _bmad-output, and asks the user only for high-risk product, auth, or destructive decisions.
• Direct BMAD: explicit /bmad <message>. This preserves manual official BMAD interaction, including menus and choices.

Example config/projects.json:

{
  "defaultProject": "agent-console",
  "projects": {
    "agent-console": {
      "repoPath": "/srv/agent-console",
      "runtime": "codex-gsd",
      "model": "gpt-5.5",
      "testCommand": "npm test",
      "buildCommand": "npm run build",
      "diffCommand": "git diff",
      "diffStatCommand": "git diff --stat",
      "maxRepairRounds": 5,
      "commandTimeoutSeconds": 1800
    },
    "agent-console-bmad": {
      "repoPath": "/srv/agent-console",
      "runtime": "bmad-official",
      "model": "gpt-5.5",
      "provider": "openai",
      "bmad": {
        "officialSourceDir": "/opt/BMAD-METHOD",
        "installOnDemand": true,
        "installModules": ["bmm"],
        "installTools": ["codex"],
        "runEvidenceAfterMessage": false,
        "commanderMaxAutoTurns": 8
      },
      "testCommand": "npm test",
      "buildCommand": "npm run build",
      "diffCommand": "git diff",
      "diffStatCommand": "git diff --stat",
      "maxRepairRounds": 5,
      "commandTimeoutSeconds": 1800
    }
  }
}

Commands

In group chats, mention the bot before the command. In direct chats, send the command directly.

/ping
/help
/auto <goal>
/new <task>
/task <task>
/task <project> <task>
/task --project <project> <task>
/task --dir <absolute repo path> <task>
/bmad <manual official BMAD message>
/newchat [title]
/sessions
/open <sessionId>
/history [sessionId]
/status
/queue
/tail [taskId]
/logs
/diff
/stop [taskId]
/correct <message>
/run [--project <project>|--dir <absolute repo path>] <shell command>
/projects
/project add <project> <absolute repo path>

Quick Start

Requirements:

• Linux server with Node.js 22+.
• A Feishu or Lark custom app with bot capability enabled.
• Event subscription using persistent connection with im.message.receive_v1.
• Bot permission to send messages and cards.
• Codex CLI installed and authenticated on the server.
• Git repositories available on the server.

Install:

git clone <your-fork-url> /opt/feishu-agent-console
cd /opt/feishu-agent-console
npm ci
npm run build

Create runtime config from examples:

cp config/feishu.example.env config/feishu.env
cp config/projects.example.json config/projects.json

Fill in:

• config/feishu.env: Feishu app id/secret and local paths.
• config/projects.json: repositories and verification commands.
• config/codex.env: API keys, model gateway variables, and optional proxy variables for Codex.

Run locally:

FEISHU_ENV_FILE=/opt/feishu-agent-console/config/feishu.env npm start

Deploy with systemd:

sudo cp deploy/feishu-agent-console.service /etc/systemd/system/feishu-agent-console.service
sudo systemctl daemon-reload
sudo systemctl enable --now feishu-agent-console
sudo journalctl -u feishu-agent-console -f

See docs/DEPLOYMENT.md for the full deployment checklist and docs/OPERATIONS.md for day-2 operations.

Repository Layout

src/
  app.ts                    # command orchestration
  config.ts                 # env and projects config loading
  feishu/                   # Feishu client, commands, cards
  queue/                    # SQLite task/session store and task runner
  runner/                   # command execution, evidence runner, markdown logs
  runtime/                  # Codex/GSD/BMAD prompt drivers
  attachments/              # Feishu file and image attachment handling
config/
  feishu.example.env
  projects.example.json
deploy/
  feishu-agent-console.service

Runtime data is intentionally ignored by Git:

config/*.env
config/projects.json
data/
logs/
dist/
node_modules/

Security Notes

This service can execute arbitrary shell commands inside configured repositories. Run it on a machine and under a Linux user account that you are comfortable dedicating to agent work.

Before publishing a fork, verify that no real values are committed for:

• Feishu app secret, verification token, or encrypt key.
• OpenAI, Anthropic, or model gateway API keys.
• SSH hosts, usernames, passwords, private proxy addresses, or internal repository paths.
• Markdown logs, SQLite databases, uploaded attachments, or generated task output.

License

No license is declared yet. Add one before publishing if you want others to reuse the code under clear terms.