codex-bee AGENTS.md

AGENTS.md

Project summary

codex-bee is an autonomous wrapper for Codex CLI. It should preserve the regular Codex terminal workflow while adding automatic continuation after each completed assistant turn.

Product goals

• Keep the Codex TUI transparent to the user.
• Detect completed turns through the Codex Stop hook system.
• Route hook payloads back to the wrapper process without cross-talk between parallel sessions.
• Support both simple continuation prompts and later AI-assisted follow-up generation.

Current stack

• Node.js 20+
• TypeScript in strict mode
• tsup for bundling the CLI entry point
• Plain CommonJS for hooks/stop-hook.cjs

Working agreements

• Keep generated artifacts in English.
• Do not compile hooks/stop-hook.cjs; it must stay directly executable by Codex hooks.
• During development, prefer the disposable sandbox-local Codex hook configuration under CODEX_BEE_SANDBOX_DIR/.codex/ over changes to ~/.codex/hooks.json.
• For terminal UI work, use the official documentation for Ink and @inkjs/ui as the primary references instead of relying on memory.
• Official Ink docs: https://github.com/vadimdemedes/ink
• Official @inkjs/ui docs: https://github.com/vadimdemedes/ink-ui and https://www.npmjs.com/package/@inkjs/ui
• Read docs/tui-isolated-development.md before starting a new TUI iteration. The current Ink renderer is the active TUI surface; iterate on what exists instead of restarting the UI direction.
• Prefer incremental experiments that validate PTY behavior, hook payloads, IPC routing, and timing before deeper implementation.
• Every code or documentation change that reaches a logical completion point must be committed immediately. Do not leave completed fixes or finished edits uncommitted in the working tree.
• After the branch is in a committed state, push it to the remote repository instead of leaving completed work only in the local git history.
• Record meaningful findings, hypotheses, and implementation results back to Trello so later agents do not repeat the same work.
• Every hypothesis that was actually tested must end with a Trello comment that states the outcome clearly enough to tell whether it was confirmed, rejected, or only partially verified.
• After a hypothesis or experiment has a result comment, move its Trello card out of ideas & backlog into the appropriate results-oriented list so the first column stays readable.
• Before pausing, stopping, or asking the user for the next step, do a Trello cleanup pass: check the first column, confirm completed work is commented, and make sure cards are in the right lists.