From 8958fb2d88315c9dfc50d4b63bf0dac1bf03a067 Mon Sep 17 00:00:00 2001 From: Antiarin Date: Thu, 12 Feb 2026 18:32:58 +0530 Subject: [PATCH] eat(codex): add project setup, quickstart bootstrap, and docs for Codex agent support --- .agents/skills/hive | 1 + .agents/skills/hive-concepts | 1 + .agents/skills/hive-create | 1 + .agents/skills/hive-credentials | 1 + .agents/skills/hive-patterns | 1 + .agents/skills/hive-test | 1 + .codex/config.toml | 12 ++ .github/workflows/codex-issue-triage.yml | 96 ++++++++++++++ AGENTS.md | 18 +++ README.md | 25 +++- docs/codex-validation.md | 51 +++++++ docs/developer-guide.md | 33 ++++- docs/environment-setup.md | 56 +++++++- docs/roadmap.md | 2 + quickstart.sh | 162 +++++++++++++++++++++++ 15 files changed, 457 insertions(+), 4 deletions(-) create mode 120000 .agents/skills/hive create mode 120000 .agents/skills/hive-concepts create mode 120000 .agents/skills/hive-create create mode 120000 .agents/skills/hive-credentials create mode 120000 .agents/skills/hive-patterns create mode 120000 .agents/skills/hive-test create mode 100644 .codex/config.toml create mode 100644 .github/workflows/codex-issue-triage.yml create mode 100644 AGENTS.md create mode 100644 docs/codex-validation.md diff --git a/.agents/skills/hive b/.agents/skills/hive new file mode 120000 index 00000000..47ca6b8e --- /dev/null +++ b/.agents/skills/hive @@ -0,0 +1 @@ +../../.claude/skills/hive \ No newline at end of file diff --git a/.agents/skills/hive-concepts b/.agents/skills/hive-concepts new file mode 120000 index 00000000..4f460b1d --- /dev/null +++ b/.agents/skills/hive-concepts @@ -0,0 +1 @@ +../../.claude/skills/hive-concepts \ No newline at end of file diff --git a/.agents/skills/hive-create b/.agents/skills/hive-create new file mode 120000 index 00000000..9247f883 --- /dev/null +++ b/.agents/skills/hive-create @@ -0,0 +1 @@ +../../.claude/skills/hive-create \ No newline at end of file diff --git a/.agents/skills/hive-credentials b/.agents/skills/hive-credentials new file mode 120000 index 00000000..610180f4 --- /dev/null +++ b/.agents/skills/hive-credentials @@ -0,0 +1 @@ +../../.claude/skills/hive-credentials \ No newline at end of file diff --git a/.agents/skills/hive-patterns b/.agents/skills/hive-patterns new file mode 120000 index 00000000..c18612b5 --- /dev/null +++ b/.agents/skills/hive-patterns @@ -0,0 +1 @@ +../../.claude/skills/hive-patterns \ No newline at end of file diff --git a/.agents/skills/hive-test b/.agents/skills/hive-test new file mode 120000 index 00000000..d2377d0e --- /dev/null +++ b/.agents/skills/hive-test @@ -0,0 +1 @@ +../../.claude/skills/hive-test \ No newline at end of file diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 00000000..aec70907 --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,12 @@ +# Project-level Codex config for Hive. +# Keep this file minimal: MCP connectivity + skill discovery. + +[mcp_servers.agent-builder] +command = "uv" +args = ["run", "--directory", "core", "-m", "framework.mcp.agent_builder_server"] +cwd = "." + +[mcp_servers.tools] +command = "uv" +args = ["run", "--directory", "tools", "mcp_server.py", "--stdio"] +cwd = "." diff --git a/.github/workflows/codex-issue-triage.yml b/.github/workflows/codex-issue-triage.yml new file mode 100644 index 00000000..9bad35a3 --- /dev/null +++ b/.github/workflows/codex-issue-triage.yml @@ -0,0 +1,96 @@ +name: Codex Issue Triage (Optional) + +on: + workflow_dispatch: + inputs: + issue_number: + description: "Issue number to triage" + required: true + type: string + issues: + types: [labeled] + +jobs: + triage: + if: | + github.event_name == 'workflow_dispatch' || + (github.event_name == 'issues' && github.event.label.name == 'codex') + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: read + issues: write + pull-requests: read + + steps: + - name: Checkout repository + uses: actions/checkout@v5 + with: + fetch-depth: 1 + + - name: Resolve issue context + id: issue_ctx + env: + EVENT_NAME: ${{ github.event_name }} + INPUT_ISSUE: ${{ github.event.inputs.issue_number }} + EVENT_ISSUE: ${{ github.event.issue.number }} + EVENT_TITLE: ${{ github.event.issue.title }} + EVENT_BODY: ${{ github.event.issue.body }} + run: | + if [ "$EVENT_NAME" = "workflow_dispatch" ]; then + echo "issue_number=$INPUT_ISSUE" >> "$GITHUB_OUTPUT" + echo "issue_title=Manual triage request" >> "$GITHUB_OUTPUT" + echo "issue_body=Triggered via workflow_dispatch for issue #$INPUT_ISSUE" >> "$GITHUB_OUTPUT" + else + echo "issue_number=$EVENT_ISSUE" >> "$GITHUB_OUTPUT" + { + echo "issue_title<> "$GITHUB_OUTPUT" + fi + + - name: Run Codex triage + id: run_codex + uses: openai/codex-action@v1 + with: + openai-api-key: ${{ secrets.OPENAI_API_KEY }} + safety-strategy: drop-sudo + codex-args: '["--model","gpt-5-mini"]' + prompt: | + You are triaging a GitHub issue for the repository ${{ github.repository }}. + + Issue number: #${{ steps.issue_ctx.outputs.issue_number }} + Issue title: ${{ steps.issue_ctx.outputs.issue_title }} + Issue body: + --- + ${{ steps.issue_ctx.outputs.issue_body }} + --- + + Produce a concise triage report with these sections: + 1) Category (bug, enhancement, question, documentation, invalid) + 2) Size estimate (small, medium, large) + 3) Duplicate risk (low/medium/high) with 1-2 keywords to search + 4) Missing information checklist + 5) Suggested maintainer comment to post + + Keep the final output short, actionable, and repository-maintainer friendly. + + - name: Post triage comment + if: steps.run_codex.outputs.final-message != '' + uses: actions/github-script@v7 + env: + TRIAGE_COMMENT: ${{ steps.run_codex.outputs.final-message }} + ISSUE_NUMBER: ${{ steps.issue_ctx.outputs.issue_number }} + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: Number(process.env.ISSUE_NUMBER), + body: `### Codex Triage (Optional)\n\n${process.env.TRIAGE_COMMENT}`, + }); diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..d3caba90 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,18 @@ +# Hive Agent Instructions (Codex) + +Use skills from `.agents/skills`: +- hive +- hive-create +- hive-concepts +- hive-patterns +- hive-test +- hive-credentials + +Rules: +- Prefer MCP tools from `agent-builder` and `tools`. +- Before assuming tool availability, list MCP tools first. +- Reuse existing Hive skill workflows; do not invent alternative flows unless required. + +Shortcut Handling: +- Treat `hive`, `hive-create`, `hive-concepts`, `hive-patterns`, `hive-test`, and `hive-credentials` as workflow invocation phrases. +- Users do not need to type skill file paths when using these phrases. diff --git a/README.md b/README.md index 4977174f..cf7f2635 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ Use Hive when you need: ### Prerequisites - Python 3.11+ for agent development -- Claude Code or Cursor for utilizing agent skills +- Claude Code, Codex CLI, or Cursor for utilizing agent skills > **Note for Windows Users:** It is strongly recommended to use **WSL (Windows Subsystem for Linux)** or **Git Bash** to run this framework. Some core automation scripts may not execute correctly in standard Command Prompt or PowerShell. @@ -120,6 +120,28 @@ hive tui hive run exports/your_agent_name --input '{"key": "value"}' ``` ## Coding Agent Support +### Codex CLI +Hive includes native support for [OpenAI Codex CLI](https://github.com/openai/codex). + +1. **Setup:** Run `./quickstart.sh` in the repo root. +2. **Config:** Ensure `.codex/config.toml` exists with `agent-builder` and `tools` MCP servers. +3. **Skills:** Hive skills are available through `.agents/skills/` and guided by `AGENTS.md`. +4. **Launch:** Start Codex CLI from the project root and use Hive skills/workflows. + +Codex uses the same MCP tools as other integrations, so agent-builder and tools behavior stays consistent. +Codex does not use Claude-style slash commands like `/hive`. + +Example Codex prompts: + +```text +Use the hive skill from .agents/skills/hive and help me build a new agent named support_triage. +First, list connected MCP tools from agent-builder and tools. +``` + +```text +Use .agents/skills/hive-create/SKILL.md to create an agent named support_triage end-to-end. +``` + ### Opencode Hive includes native support for [Opencode](https://github.com/opencode-ai/opencode). @@ -321,6 +343,7 @@ subgraph Expansion j2["Cursor"] j3["Opencode"] j4["Antigravity"] + j5["Codex CLI"] end subgraph plat["Platform"] k1["JavaScript/TypeScript SDK"] diff --git a/docs/codex-validation.md b/docs/codex-validation.md new file mode 100644 index 00000000..46ffba31 --- /dev/null +++ b/docs/codex-validation.md @@ -0,0 +1,51 @@ +# Codex Validation Notes + +Date: 2026-02-12 + +## Environment checks + +- `codex --version`: `codex-cli 0.99.0` +- Project Codex config present: `.codex/config.toml` +- Skill links present: `.agents/skills/{hive,hive-create,hive-concepts,hive-patterns,hive-test,hive-credentials}` +- `AGENTS.md` present at repo root + +## Quickstart verification + +Validated via `./quickstart.sh`: + +- `codex CLI` detected +- `AGENTS.md` check passed +- `Codex MCP config` check passed +- `Codex skills` check passed + +## MCP registration verification + +Command: + +```bash +codex mcp list +``` + +Result: + +- `agent-builder` -> `enabled` +- `tools` -> `enabled` + +## Previous non-interactive smoke test attempt (environment-dependent) + +Command: + +```bash +codex exec --cd . --skip-git-repo-check --json "List connected MCP servers and tools. If available, confirm agent-builder and tools." +``` + +Result: + +- One attempt failed due network/backend stream disconnection: + `stream disconnected before completion: error sending request for url (https://chatgpt.com/backend-api/codex/responses)` + +## Status + +- Codex integration files are configured and validated. +- MCP servers are registered and enabled in Codex. +- Remaining E2E work: run full Codex chat workflow (`hive-create` then `hive-test`) and capture outputs. diff --git a/docs/developer-guide.md b/docs/developer-guide.md index bc45d0ce..add66705 100644 --- a/docs/developer-guide.md +++ b/docs/developer-guide.md @@ -25,7 +25,8 @@ Aden Agent Framework is a Python-based system for building goal-driven, self-imp | **framework** | `/core` | Core runtime, graph executor, protocols | Python 3.11+ | | **tools** | `/tools` | MCP tools for agent capabilities | Python 3.11+ | | **exports** | `/exports` | Agent packages (user-created, gitignored) | Python 3.11+ | -| **skills** | `.claude` | Claude Code skills for building/testing | Markdown | +| **skills** | `.claude`, `.agents` | Shared skills for Claude/Codex/other coding agents | Markdown | +| **codex** | `.codex` | Codex CLI project configuration (MCP servers) | TOML | ### Key Principles @@ -46,7 +47,8 @@ Ensure you have installed: - **Python 3.11+** - [Download](https://www.python.org/downloads/) (3.12 or 3.13 recommended) - **uv** - Python package manager ([Install](https://docs.astral.sh/uv/getting-started/installation/)) - **git** - Version control -- **Claude Code** - [Install](https://docs.anthropic.com/claude/docs/claude-code) (optional, for using building skills) +- **Claude Code** - [Install](https://docs.anthropic.com/claude/docs/claude-code) (optional) +- **Codex CLI** - [Install](https://github.com/openai/codex) (optional) Verify installation: @@ -116,6 +118,29 @@ Skills are also available in Cursor. To enable: 3. Restart Cursor to load the MCP servers from `.cursor/mcp.json` 4. Type `/` in Agent chat and search for skills (e.g., `/hive-create`) +### Codex CLI Support + +Hive also supports [OpenAI Codex CLI](https://github.com/openai/codex). + +1. Run `./quickstart.sh` from repo root (it bootstraps Codex files if missing) +2. Verify `.codex/config.toml` exists and contains `agent-builder` + `tools` +3. Verify `.agents/skills/` includes `hive`, `hive-create`, `hive-concepts`, `hive-patterns`, `hive-test`, `hive-credentials` +4. Start Codex from the repo root + +Codex instructions are routed through project `AGENTS.md` and shared skill directories. +Codex does not support slash commands like `/hive`; invoke workflows using natural-language prompts. + +Example Codex prompts: + +```text +Use the hive skill from .agents/skills/hive and guide me to build an agent named support_triage. +List MCP tools first, then start the workflow. +``` + +```text +Use .agents/skills/hive-test/SKILL.md to test exports/support_triage and report failures. +``` + ### Opencode Support To enable Opencode integration: @@ -164,6 +189,10 @@ hive/ # Repository root │ ├── hive-concepts/ # Fundamental concepts │ ├── hive-patterns/ # Best practices │ └── hive-test/ # Test and validate agents +├── .codex/ # Codex CLI project config +│ └── config.toml # Codex MCP server definitions +├── .agents/ # Shared skill mountpoint +│ └── skills/ # Symlinks to Hive skills │ ├── core/ # CORE FRAMEWORK PACKAGE │ ├── framework/ # Main package code diff --git a/docs/environment-setup.md b/docs/environment-setup.md index f331188c..5f327b89 100644 --- a/docs/environment-setup.md +++ b/docs/environment-setup.md @@ -182,7 +182,44 @@ Skills are also available in Cursor. To enable: 3. Restart Cursor to load the MCP servers from `.cursor/mcp.json` 4. Type `/` in Agent chat and search for skills (e.g., `/hive-create`) -### 2. Build an Agent +### Codex CLI Support + +[OpenAI Codex CLI](https://github.com/openai/codex) is supported with project-level config. + +1. Run `./quickstart.sh` from the repo root +2. Confirm `.codex/config.toml` exists with both MCP servers: + - `agent-builder` + - `tools` +3. Confirm `.agents/skills/` contains Hive skills +4. Start Codex in the repo root and run Hive workflows using the project `AGENTS.md` + +Important: Codex does not use slash commands like `/hive`. +Use natural-language prompts that reference Hive skills. + +Example Codex prompts: + +```text +Use the hive skill from .agents/skills/hive and create a new agent named support_triage. +First list available MCP tools, then proceed step by step. +``` + +```text +Use .agents/skills/hive-concepts/SKILL.md to define goals, constraints, and node strategy for support_triage. +``` + +The numbered flow below uses **Claude Code** command examples. +For **Codex**, use equivalent natural-language prompts that reference Hive skills. + +Codex equivalents: + +```text +Use hive-create to build an agent named support_triage. +Use hive-concepts to define goals and constraints. +Use hive-patterns to improve robustness. +Use hive-test to validate the final agent. +``` + +### 2. Build an Agent (Claude Code) ``` claude> /hive @@ -534,6 +571,23 @@ Run the quickstart script in the root directory: ./quickstart.sh ``` +## Codex Setup + +Codex setup is handled by `quickstart.sh` and uses: + +- `.codex/config.toml` for MCP server configuration +- `.agents/skills/` for shared Hive skills +- `AGENTS.md` for project instruction routing + +Quick verification: + +```bash +test -f .codex/config.toml && echo "OK: Codex config" || echo "MISSING: .codex/config.toml" +for s in hive hive-create hive-concepts hive-patterns hive-test hive-credentials; do + test -d ".agents/skills/$s" && echo "OK: $s" || echo "MISSING: $s" +done +``` + ## Additional Resources - **Framework Documentation:** [core/README.md](../core/README.md) diff --git a/docs/roadmap.md b/docs/roadmap.md index c6470cb7..0d6c2150 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -68,6 +68,7 @@ subgraph Expansion j2["Cursor"] j3["Opencode"] j4["Antigravity"] + j5["Codex CLI"] end subgraph plat["Platform"] k1["JavaScript/TypeScript SDK"] @@ -254,6 +255,7 @@ classDef done fill:#9e9e9e,color:#fff,stroke:#757575 - [ ] Cursor - [ ] Opencode - [ ] Antigravity +- [ ] Codex CLI (in progress) ### File System Enhancement - [ ] Semantic Search integration diff --git a/quickstart.sh b/quickstart.sh index 39a06ad4..35a021d6 100755 --- a/quickstart.sh +++ b/quickstart.sh @@ -897,6 +897,104 @@ fi echo "" +# ============================================================ +# Step 5b: Bootstrap Codex Setup +# ============================================================ + +echo -e "${BLUE}Step 5b: Ensuring Codex setup files...${NC}" +echo "" + +CODEX_CHANGES=0 +REQUIRED_CODEX_SKILLS=(hive hive-create hive-concepts hive-patterns hive-test hive-credentials) +CODEX_SETUP_ENABLED=true + +echo -n " ⬡ codex CLI... " +if command -v codex > /dev/null 2>&1; then + CODEX_VERSION=$(codex --version 2>/dev/null || echo "installed") + echo -e "${GREEN}${CODEX_VERSION}${NC}" +else + echo -e "${YELLOW}not found${NC}" + echo -e "${YELLOW} ⚠ Install Codex CLI from https://github.com/openai/codex${NC}" +fi + +if ! prompt_yes_no " Configure Codex integration files now?" "y"; then + CODEX_SETUP_ENABLED=false + echo -e "${YELLOW} ⏭ Skipped Codex file setup${NC}" +fi + +if [ "$CODEX_SETUP_ENABLED" = true ]; then +mkdir -p "$SCRIPT_DIR/.codex" +mkdir -p "$SCRIPT_DIR/.agents/skills" + +if [ ! -f "$SCRIPT_DIR/.codex/config.toml" ]; then + cat > "$SCRIPT_DIR/.codex/config.toml" <<'EOF' +# Project-level Codex config for Hive. + +[mcp_servers.agent-builder] +command = "uv" +args = ["run", "--directory", "core", "-m", "framework.mcp.agent_builder_server"] +cwd = "." + +[mcp_servers.tools] +command = "uv" +args = ["run", "--directory", "tools", "mcp_server.py", "--stdio"] +cwd = "." +EOF + echo -e "${GREEN} ✓ Created .codex/config.toml${NC}" + CODEX_CHANGES=$((CODEX_CHANGES + 1)) +fi + +if [ ! -f "$SCRIPT_DIR/AGENTS.md" ]; then + cat > "$SCRIPT_DIR/AGENTS.md" <<'EOF' +# Hive Agent Instructions (Codex) + +Use skills from `.agents/skills`: +- hive +- hive-create +- hive-concepts +- hive-patterns +- hive-test +- hive-credentials + +Rules: +- Prefer MCP tools from `agent-builder` and `tools`. +- Before assuming tool availability, list MCP tools first. +- Reuse existing Hive skill workflows; do not invent alternative flows unless required. + +Shortcut Handling: +- Treat `hive`, `hive-create`, `hive-concepts`, `hive-patterns`, `hive-test`, and `hive-credentials` as workflow invocation phrases. +- Users do not need to type skill file paths when using these phrases. +EOF + echo -e "${GREEN} ✓ Created AGENTS.md${NC}" + CODEX_CHANGES=$((CODEX_CHANGES + 1)) +fi + +for skill in "${REQUIRED_CODEX_SKILLS[@]}"; do + target="../../.claude/skills/$skill" + link_path="$SCRIPT_DIR/.agents/skills/$skill" + + if [ -L "$link_path" ] || [ -d "$link_path" ]; then + continue + fi + + if ln -s "$target" "$link_path" 2>/dev/null; then + echo -e "${GREEN} ✓ Linked .agents/skills/$skill${NC}" + CODEX_CHANGES=$((CODEX_CHANGES + 1)) + elif cp -R "$SCRIPT_DIR/.claude/skills/$skill" "$link_path" 2>/dev/null; then + echo -e "${YELLOW} ⚠ Copied .agents/skills/$skill (symlink unavailable)${NC}" + CODEX_CHANGES=$((CODEX_CHANGES + 1)) + else + echo -e "${YELLOW} ⚠ Could not create .agents/skills/$skill${NC}" + fi +done + +if [ "$CODEX_CHANGES" -eq 0 ]; then + echo -e "${GREEN} ✓ Codex setup already present${NC}" +fi +fi + +echo "" + # ============================================================ # Step 6: Verify Setup # ============================================================ @@ -937,10 +1035,74 @@ else echo -e "${YELLOW}--${NC}" fi +echo -n " ⬡ AGENTS.md... " +if [ -f "$SCRIPT_DIR/AGENTS.md" ]; then + echo -e "${GREEN}ok${NC}" +elif [ "$CODEX_SETUP_ENABLED" = false ]; then + echo -e "${YELLOW}-- (skipped)${NC}" +else + echo -e "${RED}missing${NC}" + ERRORS=$((ERRORS + 1)) +fi + +echo -n " ⬡ Codex MCP config... " +if [ -f "$SCRIPT_DIR/.codex/config.toml" ]; then + if "$PYTHON_CMD" - <<'PY' "$SCRIPT_DIR/.codex/config.toml" > /dev/null 2>&1 +import pathlib +import sys + +config_path = pathlib.Path(sys.argv[1]) +try: + import tomllib +except ModuleNotFoundError: + raise SystemExit(1) + +with config_path.open("rb") as f: + data = tomllib.load(f) + +servers = data.get("mcp_servers", {}) +if "agent-builder" not in servers or "tools" not in servers: + raise SystemExit(1) +PY + then + echo -e "${GREEN}ok${NC}" + else + echo -e "${RED}failed${NC}" + ERRORS=$((ERRORS + 1)) + fi +elif [ "$CODEX_SETUP_ENABLED" = false ]; then + echo -e "${YELLOW}-- (skipped)${NC}" +else + echo -e "${YELLOW}--${NC}" +fi + echo -n " ⬡ skills... " if [ -d "$SCRIPT_DIR/.claude/skills" ]; then SKILL_COUNT=$(ls -1d "$SCRIPT_DIR/.claude/skills"/*/ 2>/dev/null | wc -l) echo -e "${GREEN}${SKILL_COUNT} found${NC}" +else + if [ "$CODEX_SETUP_ENABLED" = false ]; then + echo -e "${YELLOW}-- (skipped)${NC}" + else + echo -e "${YELLOW}--${NC}" + fi +fi + +echo -n " ⬡ Codex skills... " +if [ -d "$SCRIPT_DIR/.agents/skills" ]; then + MISSING_CODEX_SKILLS=() + for skill in "${REQUIRED_CODEX_SKILLS[@]}"; do + if [ ! -d "$SCRIPT_DIR/.agents/skills/$skill" ]; then + MISSING_CODEX_SKILLS+=("$skill") + fi + done + + if [ "${#MISSING_CODEX_SKILLS[@]}" -eq 0 ]; then + echo -e "${GREEN}${#REQUIRED_CODEX_SKILLS[@]} found${NC}" + else + echo -e "${RED}missing: ${MISSING_CODEX_SKILLS[*]}${NC}" + ERRORS=$((ERRORS + 1)) + fi else echo -e "${YELLOW}--${NC}" fi