ActionD

ActionD

Local AI Action Execution Engine for LGH (Local Git Hub)

English | 简体中文

ActionD is a lightweight local CI/CD engine designed for AI agents. It listens to Git events from LGH and automatically triggers plugins to run code checks, tests, builds, and more.

Features

• 🔌 Dynamic plugin discovery — plugins are discovered automatically via manifest.json, no code changes required
• 🤖 MCP integration — a built-in MCP server lets AI assistants query and control CI/CD directly
• 📡 Event-driven — reacts to git.push, git.tag, and other LGH events
• 🖥️ Web console — live monitoring dashboard at http://localhost:3000
• 🔄 Real-time streaming output — live logs over SSE (Server-Sent Events)
• ⚡ Hot reload — reload plugins without a restart
• 🔄 End-to-end workflow — dev_cycle_run does it all in one call: commit → CI → results
• ⏮️ Rollback — automatically roll back to the previous commit on failure

Terminology

• Job — one CI/CD execution record produced when a plugin reacts to a Git event. Some tool names (actiond_action_get, actiond_actions_list) carry the legacy word action; it refers to the same object as the actiond_job_* tools.
• Plugin — the executable unit registered via manifest.json that runs on trigger events (git.push, git.tag); one plugin run yields one job.
• Profile — the CI scope preset (fast / full / release) controlling which plugins run per push.

Installation

macOS / Linux (Homebrew)

brew install JoeGlenn1213/tap/actiond

Install LGH the same way (brew install JoeGlenn1213/tap/lgh) — ActionD listens to its git events.

The builtin plugin bundle (30+ check plugins) is embedded in the binary. actiond setup materializes it into ~/.localgithub/plugins, so a Homebrew or release-download install runs the same checks as a source checkout — no extra asset download needed. The web console is optional: without it the API still runs (see actiond-web or pass --web-dir).

Prerequisites

• Go 1.25+ (only when building from source)
• Python 3.8+ (used by plugins)
• LGH running locally

Build from source

git clone https://github.com/JoeGlenn1213/ActionD.git
cd ActionD
make build

Note: ActionD uses SQLite for storage (the pure-Go modernc.org/sqlite build) — no CGO is needed and make build cross-compiles freely.

Quick Start

1. One-command setup (recommended)

If this is your first run, use setup to install the builtin plugin bundle (embedded in the binary), check dependencies, create the directory layout, and verify the environment:

actiond setup

Re-running setup is safe: already-installed plugins and your local edits are never overwritten (use --force to reset them to the bundled version, --skip-plugins to skip installation entirely).

To also start the daemon in the background right after setup:

actiond setup --start

2. Start the service and check it

# 1. Make sure LGH is running
lgh serve -d

# 2. Start ActionD (daemon mode; reads LGH mappings automatically)
actiond start -d

# 3. Check status
actiond doctor

3. Open the web console

open http://localhost:3000

Default directories and auto-detection

• Plugin directories are probed in order: <binary dir>/plugins → <working dir>/plugins → ~/.localgithub/plugins
• Web static assets are auto-detected in common locations; the recommended target is publishing ActionD-Web's out/ to: ~/.localgithub/actiond-web/out
• Without an explicit --repo-root, ActionD resolves repositories through LGH mappings first, then falls back to current-directory semantics.

CLI Commands

One-command setup (v1.2+)

Recommended on first install:

actiond setup

This automatically:

• Creates the directory layout (~/.localgithub/*)
• Checks dependencies (Git, Python, Go, Node)
• Detects web assets and plugin directories
• Verifies the LGH connection

Doctor

actiond doctor

Runs 8 categories of tiered checks:

• 📦 System environment (home/base directories)
• 🔧 Dependencies (Git, Python, Go, Node, golangci-lint)
• 🔌 Service status (LGH, ActionD)
• 🌐 Ports (3000, 8080)
• 📁 Directories (repos, actions, plugins, web, artifacts)
• 💾 Storage (DB writability, config files)
• 🔌 Plugins (directories, core plugin status)
• 🌐 Web assets

Results come in three levels:

• FATAL — the system cannot work
• WARN — some functionality is affected
• INFO — informational only

If doctor reports that the Go plugins are disabled, restore them directly:

actiond plugins restore-go

Status (v1.2+)

actiond status

Shows:

• Service run status and PID
• All directory paths and their status
• LGH connection status
• Web assets and plugin directories

Build Notes

make build uses CGO_ENABLED=0 (SQLite is the pure-Go modernc.org/sqlite build), so binaries cross-compile freely.

make release defaults to the current host platform; override RELEASE_PLATFORMS="linux/amd64 linux/arm64 darwin/arm64" to build for other targets.

Start options

actiond start --help

Flags:
  -d, --daemon              run in the background
      --repo-root string    repository root directory (optional; LGH mappings take priority when omitted)
      --web-dir string      web console static file directory (optional; auto-detected by default)

Dynamic Plugin Discovery (V1.0.7+)

ActionD supports adding new plugins with zero code. Just create a manifest.json in a plugin directory:

Plugin directories

ActionD scans plugins in this order:

1. System plugins: ./plugins/ (next to the binary)
2. Development plugins: ./plugins/ (current working directory)
3. User plugins: ~/.localgithub/plugins/

manifest.json format

{
  "apiVersion": "actiond.dev/v1",
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My custom plugin",
  "command": "python3",
  "args": ["run.py"],
  "triggers": ["git.push"],
  "languages": ["python"],
  "timeout": "5m",
  "artifacts": ["report.json"]
}

Field reference

Creating a custom plugin

plugins/
└── my-plugin/
    ├── manifest.json    # plugin metadata
    └── run.py           # execution script

Example run.py:

#!/usr/bin/env python3
import json
import sys

# Read stdin input
input_data = json.load(sys.stdin)
event = input_data["event"]
repo_path = input_data["repo_path"]
artifact_dir = input_data.get("artifact_dir")

# Do the work...
print(f"Processing {event['type']} for {repo_path}", file=sys.stderr)

# Output the result (stdout)
result = {
    "status": "success",  # or "error"
    "artifacts": ["report.json"]
}
print(json.dumps(result))

Structured Result Protocol — ActionResult (v1.2+)

Plugins can return a standardized ActionResult structure that enables deep AI understanding and downstream decision gating (for example, the Policy Gate plugin reads signals produced by other plugins):

{
  "action_id": "act_8a9b2c1d",
  "plugin_id": "go-test-fast",
  "capability": "test",
  "language": "go",
  "status": "success",
  "decision": "pass",
  "timing": {
    "started_at": "2025-03-16T10:30:00Z",
    "finished_at": "2025-03-16T10:30:02Z",
    "duration_ms": 2300
  },
  "summary": {
    "message": "All 25 tests passed",
    "counts": {
      "tests_run": 25
    }
  },
  "signals": {
    "tests_passed": true
  },
  "hints": [],
  "artifacts": [{"name": "test-report.xml", "path": "test-report.xml"}]
}

Result fields

Returning structured results from a plugin

A plugin can print JSON to stdout — ActionD parses and stores it automatically:

result = {
    "status": "failure",
    "summary": "Test suite failed",
    "hints": ["Run tests locally to reproduce"]
}
print(json.dumps(result))

Alternatively, write to $ARTIFACT_DIR/result.json.

Failure Interpreter (v1.2+)

ActionD has built-in failure-pattern recognition that automatically analyzes common errors and suggests fixes:

Recognized error patterns

Analysis API

Failure analysis is implemented on the Go side in internal/interpreter (failure.go) and produces the category/type classification shown above. There is no actiond Python package — use one of these real interfaces instead:

• AI side (recommended): the MCP tool actiond_diagnose(job_id=...), which returns root cause and fix suggestions.
• HTTP side: the REST API (see the "API endpoints" section below).

Hot-reloading plugins

# Option 1: API
curl -X POST http://localhost:3000/api/plugins/reload

# Option 2: MCP
# An AI assistant can call the actiond_plugins_reload tool

Built-in Plugins

MCP Server Integration

ActionD ships with an MCP (Model Context Protocol) server so AI assistants (such as Claude) can query and control CI/CD directly.

Starting the MCP server

actiond mcp

To let the AI start/stop/restart ActionD itself over MCP, set this before launching:

ACTIOND_MCP_ALLOW_LIFECYCLE=1 actiond mcp

Available tools

To approve a blocked job, use the CLI actiond approve <job_id> or REST POST /api/actions/{id}/approve (there is no MCP tool for this).

The dev_cycle_run end-to-end workflow (V1.0.8+)

dev_cycle_run is an aggregate tool that completes the full development loop in a single MCP call:

edit code → lgh up → wait for CI → return structured results

Parameters:

Returns:

{
  "success": true,
  "verification": "pass",
  "commit": "abc123",
  "jobs": [
    {"id": "job-1", "plugin": "go-test-fast", "status": "done", "duration": "2.3s"}
  ],
  "summary": "✅ 全部通过 (2 个插件)"
}

verification is tri-state and success is true only on pass — the same vocabulary and aggregation rule as actiond_run_report:

• pass — at least one job ran and all of them passed
• fail — at least one job was observed failing
• unknown — zero jobs, a CI query error, or a timeout; never a pass

Jobs are associated to this run by LGH event id, or (fallback) by exact repo name plus commit sha — a green job from an older commit or a similarly named repo is never adopted as verification for the current change.

Typical usage:

User: AI, please fix the code and test it

AI:  [edits the code...]
     [calls dev_cycle_run(message="fix: address the failing case")]

Result: ✅ All passed (2 plugins)
        - go-lint: ✅ 0.5s
        - go-test-fast: ✅ 2.3s

Available resources

• actiond://status — server status
• actiond://plugins — plugin list
• actiond://actions — execution records

Connecting your AI client

ActionD speaks standard MCP over stdio, so any MCP-capable client works (Claude Desktop/Code, Cursor, ZCode, Windsurf, ...). For clients that take a stdio command, the server is simply:

actiond mcp

Example for Claude Code — add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "actiond": {
      "command": "/path/to/actiond",
      "args": ["mcp"],
      "env": {
        "ACTIOND_MCP_ALLOW_LIFECYCLE": "1"
      }
    }
  }
}

AI usage example

User: Check the recent CI jobs

AI:  [calls actiond_actions_list]
     There are 3 recent jobs:
     - test-python (python-pytest): ✅ success (1.3s)
     - ActionD (go-lint): ⛔ disabled
     - demo-app (java-quicktest): ✅ success (45s)

Configuration

Runtime config file: ~/.localgithub/actions/config.json

Disabling a plugin

{
  "plugins": {
    "java-quicktest": {
      "enabled": false
    }
  }
}

The core Go verification chain can also be restored directly via CLI:

actiond plugins restore-go

Overriding triggers

{
  "plugins": {
    "go-lint": {
      "triggers": ["git.tag"]
    }
  }
}

Adding a custom plugin (no manifest.json needed)

{
  "plugins": {
    "my-custom-plugin": {
      "enabled": true,
      "type": "exec",
      "command": "/usr/local/bin/my-script",
      "args": ["--verbose"],
      "triggers": ["git.push"]
    }
  }
}

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    LGH      │────▶│   ActionD   │────▶│   Plugins   │
│  (Events)   │     │  (Engine)   │     │  (Actions)  │
└─────────────┘     └─────────────┘     └─────────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
   │ Web Console │  │  MCP Server │  │    API      │
   │ (Dashboard) │  │(AI-integration)│ │  (RESTful) │
   └─────────────┘  └─────────────┘  └─────────────┘

API Endpoints

Layered Logging (v1.2+)

ActionD uses a layered logging architecture that targets different audiences with different formats:

AI summary format

{
  "timestamp": "2025-03-16T10:30:00Z",
  "layer": "ai",
  "level": "info",
  "job_id": "abc123",
  "repo": "my-project",
  "plugin": "go-test-fast",
  "message": "Tests passed",
  "data": {
    "status": "success",
    "summary": "All 25 tests passed in 2.3s",
    "hints": [],
    "artifacts": ["test-report.xml"]
  }
}

File Locations

Development

# Build
go build ./...

# Run tests
go test ./...

# Install to GOPATH
go install ./cmd/actiond

License

MIT License — see LICENSE

Related Projects

• LGH — Local Git Hub
• actiond-web — Web console UI