declawed

Telegram bridge for controlling codex on a remote machine.

Each declawed process keeps:

• one allowed Telegram chat
• one active Codex job at a time
• one continuing Codex thread for that session

Install

Release binaries are the primary distribution path. The release workflow, installer, Homebrew formula template, and cargo-binstall metadata are wired for https://github.com/bitboom/declawed. Publish the repo there, or update the URLs in Cargo.toml, install.sh, and packaging/homebrew/declawed.rb first.

One-line install from a GitHub Release:

curl -fsSL https://raw.githubusercontent.com/bitboom/declawed/main/install.sh | bash

Manual binary install:

1. Download the archive for your platform from GitHub Releases.
2. Verify the matching .sha256 file.
3. Extract declawed and place it on your PATH.

Homebrew tap skeleton:

• Formula template: packaging/homebrew/declawed.rb
• Copy it into a tap repo such as homebrew-tap/Formula/declawed.rb
• Replace the placeholder sha256 values with the hashes from the release assets

Cargo channels after publish:

cargo install declawed
cargo binstall declawed

Run

export DECLAWED_TELEGRAM_BOT_TOKEN=...
export DECLAWED_TELEGRAM_ALLOWED_CHAT_ID=123456789
export DECLAWED_CODEX_WORKDIR=/path/to/repo   # optional, defaults to current directory
declawed

During development:

cargo run

Get Your Chat ID

1. Open your bot in Telegram and send any message.
2. Read the recent update with your bot token:

curl -fsSL "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates"

3. Use message.chat.id as DECLAWED_TELEGRAM_ALLOWED_CHAT_ID.

On startup declawed prints:

• the Telegram bot username
• a direct bot link you can open in Telegram
• a QR code that opens the bot
• a one-word fruit session name for display only

How It Works

flowchart TD
    A[Start declawed] --> B[Load DECLAWED_* env]
    B --> C[Create TelegramBridge]
    C --> D[Fetch bot username with getMe]
    D --> E[Print bot link and QR for this session]
    E --> F[Long-poll Telegram getUpdates]

    F --> G{Message from allowed chat id?}
    G -- No --> H[Ignore]
    G -- Yes --> I[Handle Telegram command]

    I --> S["/status"]
    I --> X["/cancel"]
    I --> U["/mode auto or /mode danger"]
    I --> P[Plain text prompt]

    P --> J{Saved Codex thread?}
    J -- No --> K[codex exec --json --full-auto -C workdir prompt]
    J -- Yes --> L[codex exec resume --json --full-auto thread_id prompt]

    K --> M[Parse thread.started and final agent_message]
    L --> M
    M --> N[Save thread_id and last result]
    N --> O[Send summary back with sendMessage]

    S --> ST[Return active or last job state]
    X --> Q[Kill active Codex process]
    Q --> R[Mark job canceled and reply]
    U --> V[Switch future job execution mode]

Loading

Runtime notes:

• DECLAWED_TELEGRAM_ALLOWED_CHAT_ID is required. Other chats are ignored.
• Plain text continues the same Codex thread when a previous thread_id exists.
• New jobs use codex --full-auto by default.
• /mode danger switches future jobs to --dangerously-bypass-approvals-and-sandbox.
• /mode auto switches future jobs back to --full-auto.
• The fruit session name is only a display label. It is not used for authentication.
• Telegram receives short status and completion summaries, not raw terminal streaming.

Telegram commands

• plain text: run or continue the current Codex thread
• /status: show the active or last job
• /mode: show the current execution mode
• /mode auto: use codex --full-auto for future jobs
• /mode danger: use --dangerously-bypass-approvals-and-sandbox for future jobs
• /cancel: stop the active job
• /help: show the command summary

Each server run keeps one allowed Telegram chat and one continuing Codex thread.

Release

Tagging vX.Y.Z on GitHub triggers the release workflow in .github/workflows/release.yml. It builds:

• x86_64-unknown-linux-musl
• x86_64-apple-darwin
• aarch64-apple-darwin

Each release uploads:

• declawed-<target>.tar.gz
• declawed-<target>.tar.gz.sha256

Typical release flow:

cargo test
cargo clippy --all-targets --all-features -- -D warnings
git tag v0.1.1
git push origin main --tags