codex-claw

codex-claw is a Bun + TypeScript Telegram-native generalized agent harness that is intended to combine grammY, the Codex SDK, and OpenAI-backed tooling in a small bot-friendly repository.

What It Does

This bot runs locally on your machine and connects one Telegram chat to one persistent Codex thread.

• Normal Telegram messages are sent to the current Codex thread.
• The bot keeps the session alive between messages until you reset it.
• Only one run is allowed at a time for the chat.
• The bot keeps an operational workspace for session state and logs, but it may still read or modify files outside that workspace if the request calls for it.

Requirements

• Bun
• A Telegram bot token from @BotFather
• Local Codex CLI authentication via codex login

Setup

1. Authenticate the local Codex CLI.

codex login

This project reuses the local Codex CLI authentication by default.

2. Start the bot directly with bunx.

bunx @npmc_5/codex-claw

bunx downloads the published CLI and runs it immediately, so no separate install step is required.

3. On first start, if no Telegram bot token has been saved yet, the app will prompt:

TELEGRAM_BOT_TOKEN을 입력하세요:

After you enter it once, the value is saved to ~/.codex-claw/local-config.json and reused on later runs. No separate configuration file is required for normal usage.

Telegram Usage

Once the process is running, open your bot in Telegram and send plain text instructions.

Example prompts:

• 이 프로젝트 구조 요약해줘
• ~/dev/my-app 에서 테스트 실패 원인 찾아줘
• 현재 작업 내용을 바탕으로 README 초안 써줘
• 이 경로의 파일들을 보고 다음 작업 계획 세워줘: /Users/me/project

The bot will keep using the same Codex thread for follow-up messages in that chat.

Example:

1. 이 저장소 구조 파악해줘
2. 그럼 다음으로 테스트부터 돌려봐
3. 방금 수정한 내용 요약해줘

Commands

• /status shows whether the persistent Codex thread is idle or running.
• /reset clears the current session after the active run has stopped.
• /abort requests cancellation for the active run.
• /help shows the command summary.

Notes:

• /reset only succeeds when no run is active.
• /abort is best-effort cancellation for the current in-flight turn.
• If you send a new message while a run is still active, the runtime rejects the overlapping run.

Runtime Model

codex-claw uses a fixed workspace at ~/.codex-claw/workspace by default.

This workspace is the bot's operational home and contains things like:

• state/session.json for the persistent chat session metadata
• logs/YYYY/MM/DD/*.json for structured run logs

The fixed operational workspace stores local state and logs under predictable paths, but the agent is not restricted to that directory for user-requested work. When Codex decides it needs to inspect or modify files outside that workspace, it may still read and write outside that workspace.

Repository Maintenance

This README intentionally documents the published bunx flow. Repository checks and release steps remain in package.json scripts.

Publishing

Before publishing, make sure your npm registry auth is available to Bun.

bun pm whoami

Recommended release flow:

1. Run the full checks.

bun run check

2. Inspect the package tarball and registry publish dry-run.

bun run pack:dry-run
bun run publish:dry-run

3. Bump the version.

bun run release:patch
# or
bun run release:minor
# or
bun run release:major

4. Publish to npm.

bun run publish:npm

Notes:

• prepublishOnly runs bun run check before publish.
• This package is intended for Bun-based usage and is published through bun publish.

Smoke Testing

See docs/plans/smoke-test-checklist.md for the manual end-to-end checklist used to verify the local Telegram flow.