Hexabot AI Coding Agent Action

hexabot-action-ai-coding-agent packages the ai_coding_agent workflow action for Hexabot v3. It runs a coding harness inside a Docker sandbox, optionally clones a repository, resumes per-thread agent sessions, and returns a workflow-safe result with changed files, diffs, run metadata, and structured plan state.

Watch the YouTube video demo.

Example : https://github.com/marrouchi/Slack2PR

Features

• Pluggable harnesses: Codex, Claude Code, OpenCode, and Grok Build.
• Docker-backed TanStack AI sandboxes with per_thread reuse or per_run isolation.
• Git source support for GitHub shorthand, HTTPS Git URLs, and empty workspaces.
• Credential-based LLM and Git token injection without exposing raw secret values in workflow YAML.
• Optional GitHub CLI bootstrap for opening pull requests from inside the sandbox.
• Thread-scoped session memory for harness session resume.
• Optional or required hexabot-state plan/todo contract for deterministic workflow loops.
• File event and diff collection for downstream workflow steps.

Prerequisites

• Hexabot v3.3 or newer, running @hexabot-ai/api.
• Node.js 24.17.x, matching the current Hexabot v3.3 engine.
• Docker available to the Hexabot API process.
• A Hexabot credential for the selected coding harness provider.
• Optional Git credential with clone/push access to the target repository.

Installation

Install the package in the same workspace or deployment that runs @hexabot-ai/api:

npm install hexabot-action-ai-coding-agent

Restart the Hexabot API after installation. The action is registered as:

ai_coding_agent

Workflow Usage

Minimal task against a GitHub repository:

defs:
  implement_change:
    kind: task
    action: ai_coding_agent
    inputs:
      prompt: =$input.text
      source_type: github
      repository: Hexastack/Hexabot
      ref: main
    settings:
      harness: codex
      model: gpt-5.3-codex
      agent_api_key: <hexabot-credential-id>
      github_token: <hexabot-git-credential-id>
      install_gh: true

The raw result is available to later tasks as $output.implement_change.

Inputs

Common input fields:

| Field | Purpose | | --- | --- | | input_mode | Use a direct prompt or build the task from recent conversation history. | | prompt | Coding task sent to the sandboxed harness. | | source_type | github, git, or none. | | repository | GitHub owner/repo, GitHub URL, or HTTPS Git URL. Required unless source_type is none. | | ref | Branch, tag, or commit to check out. | | depth | Clone depth, either a positive number or full. | | session_id | Optional explicit harness session id. Defaults to the session stored in thread memory. |

Settings

Common settings:

| Field | Purpose | | --- | --- | | harness | codex, claude_code, grok_build, or opencode. | | model | Harness-specific model identifier. | | agent_api_key | Hexabot credential injected for the selected harness. | | github_token | Optional Git token credential for private clone, push, and gh pr create. | | docker_image | Docker image for the sandbox. Defaults to node:24. | | setup_commands | Commands run while preparing the workspace. | | sandbox_lifecycle | per_thread or per_run. | | keep_alive | Idle timeout for reusable per-thread sandboxes. | | session_memory_slug | Thread memory slug used for session and plan state. Defaults to ai_coding_agent. | | plan_mode | off, optional, or required. | | allow_commands, ask_commands, deny_commands | Sandbox command policy rules. | | file_write_policy, network_policy | Sandbox capability policy decisions. |

Harness credential defaults:

| Harness | Default env var | | --- | --- | | codex | CODEX_API_KEY | | claude_code | ANTHROPIC_API_KEY | | grok_build | XAI_API_KEY | | opencode | OPENAI_API_KEY |

Output

The action returns JSON-serializable output with:

• ok, error, harness, model, provider, thread_id, run_id, session_id, and sandbox_id.
• text, text_truncated, finish_reason, and usage.
• plan_status, plan_error, plan, and todos when the plan contract is enabled or emitted.
• event_counts, optional compact events, changed files, and collected diffs.

Session Memory

The action seeds a thread-scoped memory definition with slug ai_coding_agent on application bootstrap when the Hexabot memory service is available. Attach that memory definition to workflows that should resume the same harness session across multiple runs in the same thread.

The default session_id input expression reads:

=$context.memory.ai_coding_agent.sessionId

When the harness returns a session id, the action persists it back to the same memory record. If the harness emits a valid hexabot-state block, the parsed plan and todos are also persisted.

Development

npm install
npm test
npm run lint
npm run typecheck
npm run build
npm run check:dist
npm pack --dry-run

build:publish removes generated output, builds dist, and verifies that the package contains dist/index.js and dist/ai-coding-agent.action.js.

Publishing

Release helpers:

npm run release:patch
npm run release:minor

Both commands create an npm version commit and tag, then push main with tags. The GitHub Actions release workflow runs on v* tags, installs with npm ci, runs tests, lint, typecheck, build, npm pack --dry-run, and publishes to npm when the version is not already published.

Required repository secret:

• NPM_TOKEN: npm automation token with publish access for hexabot-action-ai-coding-agent.

License

This software is licensed under the Fair Core License, FCL-1.0-ALv2. Full terms are available in LICENSE.md.