pocket-coding 0.1.1

PoCo: Pocket Coding for Feishu

PoCo

中文说明

PoCo is the product name. The Python package name is pocket-coding.

PoCo is a local TUI for running Codex app-server behind a Feishu bot.

• DM the bot for management
• Use Feishu groups as project workspaces
• Run one Codex worker per project group
• Stream progress back by creating and editing Feishu messages

Quick Start

Install:

pip install pocket-coding

Or from source:

pip install .

Start:

poco

Non-interactive config is also supported:

poco config app_id "cli_xxx"
poco config app_secret "your-secret"
poco config --show

In the TUI:

1. Fill in Feishu App ID and App Secret
2. Click Save & Restart
3. Add the bot to a project group
4. In that group, run:

/poco name my-project
/poco cwd /path/to/project
/poco mode mention
/poco enable

After that:

• DM the bot with /poco workers or /poco status my-project
• In the group, use /poco ... for PoCo commands
• In the group, all non-/poco text is forwarded to Codex

To attach the current group worker to an existing Codex CLI session:

/poco attach <session_id>

PoCo will try to import the session working directory from local Codex state and bind the current worker to that session.

How It Works

• DM with the bot: management console
• Group chat with the bot: project workspace
• Each project group gets its own Codex worker process
• Each group must configure its own working directory before enable
• PoCo connects to Feishu in long-connection mode, so no public callback URL is required

Commands

DM commands:

• /poco help
• /poco workers
• /poco list
• /poco sessions [limit]
• /poco status <worker_alias|group_chat_id>
• /poco stop <worker_alias|group_chat_id>
• /poco reset <worker_alias|group_chat_id>
• /poco remove <worker_alias|group_chat_id>

Group commands:

• /poco help
• /poco mode <mention|auto>
• /poco attach <session_id>
• /poco cwd <path>
• /poco enable
• /poco disable
• /poco reset
• /poco new
• /poco name <alias>
• /poco unname
• /poco status
• /poco stop
• /poco remove

Feishu Requirements

Use a self-built enterprise app, not a custom webhook bot.

Required capabilities:

• Bot enabled
• Event subscription: im.message.receive_v1
• Permission to send messages
• Permission to update messages

Recommended:

• Long connection mode

TUI

Views:

• Dashboard
• Config
• Logs

The TUI is intentionally plain for older terminals:

• no header/footer chrome
• no button bar
• simple text navigation

Shortcuts:

• 1 or F2: Dashboard
• 2 or F3: Config
• 3 or F4: Logs
• Ctrl+S: Save config
• Ctrl+R: Save and restart
• q: Quit

Files

• Config: ~/.config/poco/config.json
• State: ~/.local/state/poco/

Development

Build packages:

uv build

Quick syntax check:

uv run python -m py_compile poco/__init__.py poco/app.py poco/bridge.py