Metadata-Version: 2.4
Name: pocket-coding
Version: 0.1.0
Summary: PoCo: Pocket Coding for Feishu
Author: PoCo contributors
Keywords: bot,codex,feishu,lark,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.11
Requires-Dist: lark-oapi==1.5.3
Requires-Dist: textual<1,>=0.75
Description-Content-Type: text/markdown

# PoCo

[中文说明](README.zh-CN.md)

`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:

```bash
pip install pocket-coding
```

Or from source:

```bash
pip install .
```

Start:

```bash
poco
```

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:

```text
/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

## 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 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 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`

Top actions:

1. `Save & Restart`
2. `Save Config`
3. `Dashboard`
4. `Config`
5. `Logs`
6. `Quit`

Shortcuts:

- `F2`: Dashboard
- `F3`: Config
- `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:

```bash
uv build
```

Quick syntax check:

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