chnjinlei/hive
1
0
Fork 0
Code Issues Pull Requests Actions 41 Packages Projects Releases Wiki Activity

eat(codex): add project setup, quickstart bootstrap, and docs for Codex agent support

Browse Source
This commit is contained in:
Antiarin
2026-02-12 18:32:58 +05:30
parent 170a0918f7
commit 8958fb2d88
15 changed files with 457 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/hive
Symlink
+1
View File
@@ -0,0 +1 @@
../../.claude/skills/hive
.agents/skills/hive-concepts
Symlink
+1
View File
@@ -0,0 +1 @@
../../.claude/skills/hive-concepts
.agents/skills/hive-create
Symlink
+1
View File
@@ -0,0 +1 @@
../../.claude/skills/hive-create
.agents/skills/hive-credentials
Symlink
+1
View File
@@ -0,0 +1 @@
../../.claude/skills/hive-credentials
.agents/skills/hive-patterns
Symlink
+1
View File
@@ -0,0 +1 @@
../../.claude/skills/hive-patterns
.agents/skills/hive-test
Symlink
+1
View File
@@ -0,0 +1 @@
../../.claude/skills/hive-test
.codex/config.toml
+12
View File
@@ -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 = "."
.github/workflows/codex-issue-triage.yml
+96
View File
@@ -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<<EOF"
echo "$EVENT_TITLE"
echo "EOF"
echo "issue_body<<EOF"
echo "$EVENT_BODY"
echo "EOF"
} >> "$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}`,
});
AGENTS.md
+18
View File
@@ -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.
README.md
+24 -1
View File
@@ -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"]
docs/codex-validation.md
+51
View File
@@ -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.
docs/developer-guide.md
+31 -2
View File
@@ -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
docs/environment-setup.md
+55 -1
View File
@@ -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)
docs/roadmap.md
+2
View File
@@ -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
quickstart.sh
+162
View File
@@ -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