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.