ActionView.Api 0.22.0

ActionView

ActionView is a review queue and action dashboard for DevOps and engineering workflows. External tools -- CI/CD pipelines, incident analyzers, GitHub bots, or any custom automation -- drop structured JSON entries into an inbox directory. ActionView picks them up, displays them in a real-time web dashboard, and lets you take actions (approve deploys, review PRs, acknowledge incidents) directly from the UI or the command line.

How It Works

External Tool                ActionView                      You
─────────────               ──────────                     ───
CI pipeline  ─┐
GitHub bot   ─┼─► inbox/  ─► active/  ─► Web Dashboard ─► Click "Approve"
Alerting     ─┘              (watch)      or CLI            ─► archive/

1. An external system writes a JSON file into the inbox/ directory.
2. ActionView's file watcher picks it up, validates it, and moves it to active/.
3. The entry appears in the dashboard (pushed via SignalR) and/or the CLI.
4. You review the content and trigger an action (HTTP call, CLI command, or dismiss).
5. The entry moves to archive/ with an outcome record, or is deleted.

Invalid files are moved to errors/ with a companion .error.txt explaining the failure.

Installation

Prerequisites

• .NET 10 SDK
• Node.js (for the web dashboard)

Install as Global Tools

# Build the NuGet packages
dotnet pack src/ActionView.Cli -c Release
dotnet pack src/ActionView.Api -c Release
dotnet pack src/ActionView.Mcp -c Release

# Install the CLI
dotnet tool install --global --add-source ./artifacts ActionView.Cli

# Install the web server
dotnet tool install --global --add-source ./artifacts ActionView.Api

# Install the MCP server
dotnet tool install --global --add-source ./artifacts ActionView.Mcp

Build From Source

dotnet build src/ActionView.slnx

Run Tests

dotnet test src/ActionView.Tests

Usage

Web Dashboard

Start the server:

# As a global tool
actionview-server --config path/to/actionview.json

# From source (development mode — auto-launches Vite with hot reload)
dotnet run --project src/ActionView.Api

The dashboard is served at http://localhost:5000. In development mode, Vite runs on port 5173 and is reverse-proxied automatically.

The dashboard provides:

• Active view -- all pending entries, ordered by pinned → priority → severity → date (or a sort field/direction you choose), with real-time updates via SignalR.
• Saved views -- named filter presets (by tag and/or type) that split the feed into lanes such as Work and Personal. Configure them in actionview.json or manage them from the UI (add, rename, change icon/tags, reorder, delete); each pill shows a live count, and an always-present All view shows everything.
• Filtering & sort -- filter by type, severity, source, tags (with Any/All matching), and free-text search; sort by created/priority/severity/title, ascending or descending. Tags appear on each row and are click-to-filter.
• History view -- archived entries with outcomes, the same saved views / filters / sort, and a paginated Load more.
• Detail panel -- rendered content blocks (markdown, code with syntax highlighting, tables, JSON, key-value pairs, alerts, links) and action buttons. Blocks marked editable can be edited inline (persisted, with an original/diff view and one-click revert), and each action button shows a command preview and its last-run outcome.
• Activity log -- a per-entry, append-only history of everything that ran against an entry (actions, section approvals, edits, dismiss/delete) with command, exit status, duration, and streamed output. Survives archive/dismiss/delete. Opened from the History icon in the detail panel; also exposed globally at /api/history/actions.
• Live action progress -- actions run as background jobs: the button shows a spinner, elapsed timer, streamed output tail, and a Cancel button while running, then the success/failure outcome. Long-running commands never block the UI.
• Live indicators -- connection status, unread badges.

CLI

actionview [command] [options] --config path/to/actionview.json

Command	Description
add [-f <file>] [-j <json>] [--set k=v] [--group-id <id>] [--group-label <s>] [--priority <n>] [--pin] [--wait] [--strict]	Add a JSON entry to the inbox (accepts file, inline JSON, or stdin). --set/--group-id/etc. patch top-level fields at submit time; --wait validates synchronously and fails fast instead of discovering errors later in errors/.
validate [-f <file>] [-j <json>] [--type <t>] [--strict]	Validate an entry against the schema + its type template without adding it. Prints { ok, errors[], warnings[] } and exits non-zero on failure.
list [--type] [--severity] [--source] [--search] [--tags] [--tag-mode any\|all] [--sort created\|priority\|severity\|title] [--dir asc\|desc] [--view <id\|name>]	List active entries in a table
dismiss <id>	Archive an entry (supports partial ID matching)
delete <id> [-f\|--force]	Permanently delete an entry
pin <id>	Toggle pin on an active entry
stats	Show counts by type, severity, and directory
schema	Print the entry JSON schema to stdout
template list	List all registered templates
template show <type>	Show a template's full definition
template register [-f <file>] [-j <json>]	Register a new entry type template
template remove <type>	Remove a registered template

MCP Server

ActionView includes an MCP (Model Context Protocol) server that exposes the review queue to AI agents. It runs as a separate binary over stdio transport.

Running the MCP server

# As a .NET tool
actionview-mcp [--read-only] [--config path/to/actionview.json]

# Via dnx (no install required, .NET 10+)
dnx ActionView.Mcp [--read-only]

# From source
dotnet run --project src/ActionView.Mcp -- --read-only

MCP client configuration

Add to your MCP client configuration (e.g., Claude Desktop, OpenCode, etc.):

{
  "mcpServers": {
    "actionview": {
      "command": "actionview-mcp",
      "args": ["--read-only", "--config", "/path/to/actionview.json"]
    }
  }
}

Or with dnx (no prior install needed):

{
  "mcpServers": {
    "actionview": {
      "command": "dnx",
      "args": ["ActionView.Mcp", "--", "--read-only"]
    }
  }
}

Available MCP tools

Tool	Mode	Description
list_entries	read	List active entries with optional filters (type, severity, source, tags, tagMode any/all, search, view) and sort (sort, dir)
get_entry	read	Get a single entry by ID (supports partial ID match)
list_templates	read	List all registered templates
get_template	read	Get a template's full definition
get_stats	read	Get dashboard statistics
get_schema	read	Get the entry JSON schema
validate_entry	read	Validate candidate entry JSON against the schema + type template without adding it; returns { ok, errors[], warnings[] } with JSON paths
add_entry	write	Add a new entry to the review queue (validates first; returns a structured report on failure)
dismiss_entry	write	Dismiss/archive an active entry
delete_entry	write	Permanently delete an active entry
pin_entry	write	Toggle pin on an active entry
register_template	write	Register or update a template
remove_template	write	Remove a registered template

The --read-only flag restricts the server to read-mode tools only (plus add_entry is excluded). Write tools are only available when --read-only is not set.

Adding Entries

Any tool that can write a JSON file can create entries. Drop a .json file into the inbox directory:

# Copy a sample entry into the inbox
cp samples/pr-review.json data/inbox/

# Or use the CLI with a file
actionview add -f samples/deploy-approval.json

# Or pass inline JSON
actionview add -j '{"type":"alert","source":"monitoring","title":"Disk full on db-1"}'

The add command (and template register) also accepts JSON from stdin. If no --file or --json flag is given and input is piped, stdin is read automatically:

# Pipe from another command
cat entry.json | actionview add
curl -s https://api.example.com/pending-review | actionview add

# Explicit stdin via --file -
actionview add --file - < entry.json

This makes it easy to integrate ActionView into shell pipelines and scripts.

REST API

The server exposes these endpoints:

Method	Path	Description
GET	/api/entries	List active entries (query: type, severity, source, tags, tagMode, search, sort, dir)
POST	/api/entries	Ingest an entry (raw JSON body). On failure returns 400 with { error: "validation_failed", validation: { ok, errors[], warnings[] } }.
POST	/api/entries/validate	Validate an entry (raw JSON body) without ingesting. Query: strict, includeNormalized. Returns { ok, errors[], warnings[] }.
GET	/api/entries/{id}	Get entry detail (marks as viewed)
POST	/api/entries/{id}/actions/{actionIndex}	Start an entry action. Runs as a background job; returns 202 with the ActionJob. Progress/completion arrive over SignalR.
POST	/api/entries/{entryId}/blocks/{path}/actions/{actionIndex}	Start a block/section action, addressed by a dot-delimited block path (e.g. 3.0 = content[3].content[0]), so nested-section actions resolve. Also a background job.
PATCH	/api/entries/{entryId}/blocks/{path}	Edit a block's text ({ value }). Persists to the entry, capturing the original on first edit.
POST	/api/entries/{entryId}/blocks/{path}/revert	Revert an edited block to its captured original.
GET	/api/entries/{id}/history	Per-entry action/edit audit log (newest first). Survives archive/dismiss/delete.
GET	/api/jobs	List active (pending/running) action jobs. Query: entryId.
GET	/api/jobs/{jobId}	Get an action job snapshot (status, exit code, output tail).
POST	/api/jobs/{jobId}/cancel	Cancel a running action job (kills the process tree).
POST	/api/entries/{id}/dismiss	Dismiss (archive) an entry
DELETE	/api/entries/{id}	Permanently delete an entry
GET	/api/history	List archived entries (query: type, severity, source, tags, tagMode, search, sort, dir, limit, offset)
GET	/api/history/{id}	Get archived entry detail
GET	/api/history/actions	Global action activity feed across all entries (newest first). Query: limit.
GET	/api/stats	Dashboard statistics
GET	/api/views	List saved views
PUT	/api/views	Replace the saved views and persist them back to actionview.json
GET	/api/views/counts	Active-entry counts per view (drives the pill badges)
GET	/api/config	Client-facing config slice (e.g. the default tagMatchMode)
GET	/api/files?path={path}	Serve a local file referenced by an entry. Gated by fileAccess.allowedRoots in actionview.json.
GET	/api/entries/{id}/export?format={md\|html\|json}	Export an entry (active or archived) as Markdown, HTML, or raw JSON for archiving / printing.

A SignalR hub is available at /hubs/entries and broadcasts EntriesAdded, EntryUpdated, EntryArchived, EntryDeleted, ConfigChanged (config hot-reload), and the action-job lifecycle events ActionJobStarted, ActionJobProgress, and ActionJobFinished.

Validation

Entries are validated against the published entry schema (JSON Schema draft 2020-12) plus, if one is registered, the entry type's template. The same pipeline backs the CLI validate command, the MCP validate_entry tool, and POST /api/entries/validate.

The intended flow for producers — especially LLM agents — is emit → validate → fix, rather than reasoning about the whole schema up front:

1. Emit a best-effort entry.
2. Validate it (validate_entry / actionview validate / POST /api/entries/validate).
3. Fix the reported errors and resubmit.

The report is compact and machine-readable so the loop stays cheap:

{
  "ok": false,
  "errors": [
    { "path": "/severity", "code": "schema.enum", "message": "Value should match one of the values specified by the enum" },
    { "path": "/content/0", "code": "schema.required", "message": "Required properties [\"type\"] are not present" }
  ],
  "warnings": [
    { "path": "/content", "code": "block.missingRequired", "message": "Missing required 'keyValue' content block 'Pull Request Details' expected by the 'pr-review' template." }
  ]
}

• Errors block ingestion. Warnings are advisory and, by default, do not block — they surface template issues (missing required blocks, disallowed tags) without dropping the entry.
• Set strict (--strict, ?strict=true, template strict, or ingest.strict) to promote warnings to errors and reject imperfect entries into errors/ with the same structured reason.
• includeNormalized (off by default) echoes the normalized entry; leave it off to keep responses token-cheap for large entries.

Configuration

ActionView is configured via a actionview.json file:

{
  "dataDirectory": "data",
  "listenUrl": "http://localhost:5173",
  "watchConfig": true,
  "tagMatchMode": "any",
  "undoWindowSeconds": 10,
  "ingest": {
    "strict": false
  },
  "actions": {
    "maxConcurrentJobs": 4,
    "defaultTimeoutSeconds": 0,
    "outputTailLines": 200
  },
  "views": [
    { "id": "work", "name": "Work", "icon": "briefcase", "tags": ["work"] },
    { "id": "personal", "name": "Personal", "icon": "user", "tags": ["personal"] },
    { "id": "deploys", "name": "Deploys", "icon": "rocket", "type": "deploy" }
  ],
  "notifications": {
    "enabled": false
  },
  "secrets": {
    "CI_TOKEN": "env:CI_API_TOKEN",
    "JIRA_TOKEN": "my-literal-token"
  },
  "fileAccess": {
    "allowedRoots": ["C:/temp/Zakira.Replay"],
    "maxFileSizeBytes": 20971520
  }
}

Fields

Field	Type	Default	Description
dataDirectory	string	~/.actionview/	Root directory containing inbox/, active/, archive/, and errors/ subdirectories. Relative paths are resolved against the config file location.
listenUrl	string	http://localhost:5173	URL the API host listens on. CLI --urls/--port override it.
watchConfig	bool	true	Watch actionview.json for external edits and hot-reload the runtime-safe slices (views, tagMatchMode, notifications, secrets) without a restart, pushing a ConfigChanged event to open dashboards. Startup-bound settings (dataDirectory, fileAccess, templates, ingest, listenUrl) still require a restart. Read once at startup.
tagMatchMode	"any" | "all"	any	Default combine mode for multi-tag filters: any (OR) or all (AND). A per-view tagMatch and the dashboard's Any/All toggle override it.
undoWindowSeconds	int	10	Default seconds an action's undo toast stays available. A per-action undoWindowSeconds overrides it.
ingest.strict	bool	false	When true, entries that fail schema validation or produce normalization warnings (e.g. a missing required content block, a disallowed tag) are rejected at ingest and routed to errors/ with a precise reason, instead of shipping with a logged warning. The non-destructive default preserves ActionView's promise never to silently drop a review item; strict producers opt in per submission (--strict, ?strict=true, strict:true), per type (template strict), or globally here.
actions.maxConcurrentJobs	int	4	Maximum action jobs running at once. Excess jobs queue as pending.
actions.defaultTimeoutSeconds	int	0	Per-job timeout in seconds. When > 0, a job that exceeds it is cancelled (process tree killed) and marked failed. 0 = no timeout.
actions.outputTailLines	int	200	Maximum streamed output lines retained on a running job (rolling tail).
views	object[]	[]	Saved filter presets ("views"). Each: id, name, optional icon (Lucide name), type, tags (string[]), and tagMatch (any/all). Editable from the dashboard, which persists changes back to this file. The built-in All view is always present and not stored here.
notifications.enabled	bool	true	Enable Windows toast notifications when new entries arrive.
secrets	object	{}	Key-value map of secrets used in action command placeholders.
fileAccess.allowedRoots	string[]	[]	Absolute (or config-relative) directory paths whose contents /api/files is allowed to serve. Required for file:// image URLs in entries to load. Empty = no local files served.
fileAccess.maxFileSizeBytes	int	20971520 (20 MiB)	Maximum file size returned by /api/files. Larger files return HTTP 413.

Config File Resolution

The config file is resolved in this order (first match wins):

1. --config CLI argument
2. ACTIONVIEW_CONFIG environment variable
3. $XDG_CONFIG_HOME/actionview/actionview.json
4. ActionView:ConfigPath in appsettings.json
5. ./actionview.json in the current directory

Secrets

Secrets are referenced in action commands using {{PLACEHOLDER}} syntax. They appear in HTTP URLs, headers, request bodies, and CLI arguments.

A secret value can be:

• A literal string -- used as-is.
• An environment variable reference -- prefixed with env:, e.g. "env:CI_API_TOKEN" reads the CI_API_TOKEN environment variable at runtime.

If a placeholder is not found in the secrets map, ActionView falls back to looking up the placeholder name directly as an environment variable. Unresolved placeholders are left in place.

{
  "secrets": {
    "CI_TOKEN": "env:CI_API_TOKEN",
    "SLACK_WEBHOOK": "https://hooks.slack.com/services/T00/B00/xxx"
  }
}

Then in an action command:

{
  "command": {
    "type": "http",
    "method": "POST",
    "url": "https://api.example.com/deploy",
    "headers": {
      "Authorization": "Bearer {{CI_TOKEN}}"
    }
  }
}

Entry Format

Entries are JSON files conforming to the entry schema. You can print the schema with actionview schema.

Minimal Entry

{
  "type": "alert",
  "source": "monitoring",
  "title": "CPU usage above 90% on prod-web-3"
}

Full Entry Structure

{
  "schemaVersion": "1",
  "type": "pr-review",
  "source": "github-orchestrator",
  "title": "PR #482: Add user preference caching layer",
  "subtitle": "repo: acme/backend",
  "severity": "medium",
  "icon": "git-pull-request",
  "tags": ["backend", "performance"],
  "content": [ ],
  "actions": [ ]
}

Field	Required	Description
type	yes	Category string (e.g. pr-review, deploy, incident)
source	yes	Identifies the tool that created the entry
title	yes	Primary display text
schemaVersion	no	Must be "1" if present
subtitle	no	Secondary display text
severity	no	low, medium (default), high, or critical
icon	no	Lucide icon name
tags	no	Array of string labels
content	no	Ordered list of content blocks to render
actions	no	List of action buttons

Content Blocks

The content array accepts these block types:

Type	Description	Key Fields
markdown	GFM markdown with math (KaTeX), task lists, footnotes; embedded images render as click-to-enlarge thumbnails	body
code	Syntax-highlighted code with copy button, wrap/line-no toggles, and inline per-line annotations	body, language, filename, highlight, annotations
diff	Real unified/split diff view with add/remove gutters and per-hunk collapse	body (unified diff), oldFilename, newFilename, mode
json	Foldable, syntax-colored JSON tree with copy button	body
table	Sortable, filterable table with rich cells (link/status/badge/code/copy/markdown/image)	columns, rows, sortable, filterable
keyValue	Key-value grid with the same rich-cell value types as tables	pairs
link	One or many external links with optional description body and icon	url / links[], body, icon
image	Thumbnail with click-to-enlarge lightbox; supports annotations + timestamp links	url, alt, caption, maxWidth, imageAnnotations, timestampUrl
gallery	Grid of images sharing one lightbox carousel with prev/next + zoom	images[]
video	YouTube / Vimeo / file video with optional clipping and chapter list	url, provider, videoId, startTime, endTime, chapters
file	Downloadable attachment via /api/files (gated by fileAccess.allowedRoots)	url, filename, fileSize, mimeType
timeline	Vertical timeline of dated events (level + icon + markdown body per event)	events[]
tabs	Tab strip; each tab carries its own content[] of nested blocks	tabs[]
stat	Big-number stat with optional delta indicator and sparkline	value, delta, trend, unit, sparkline
chart	Line / bar / area / pie chart for monitoring snapshots	chartType, series, xAxis
diagram	Mermaid diagram (flowcharts, sequence, gantt)	body (Mermaid source)
beforeAfter	Image slider revealing before/after via a draggable handle	beforeUrl, afterUrl, beforeLabel, afterLabel
section	Collapsible group (default-collapsed + badge) with nested blocks	title, content, actions, defaultCollapsed, badge
alert	Colored banner with markdown body, optional dismiss, and inline actions	body, level, dismissible, actions
divider	Horizontal rule	(no fields)

Any block also accepts two optional fields: id (a stable identifier used for outcome markers and {{content.ID}} command references) and editable (when true, the block's text can be edited inline in the dashboard — persisted to the entry, with an original/diff view and one-click revert).

Actions

Actions define buttons that execute commands when clicked:

{
  "label": "Approve Deploy",
  "style": "success",
  "confirmMessage": "Are you sure you want to approve this deployment?",
  "command": {
    "type": "http",
    "method": "POST",
    "url": "https://ci.example.com/api/deploy/{{DEPLOY_ID}}/approve",
    "headers": {
      "Authorization": "Bearer {{CI_TOKEN}}"
    },
    "body": "{\"approved_by\": \"actionview\"}"
  },
  "onSuccess": "archive"
}

Field	Description
label	Button text
style	default, primary, success, or danger
confirmMessage	If set, a confirmation dialog (or form heading) is shown before execution
command.type	http or cli
parameters	Optional list of inputs the user supplies before the action runs (see below)
onSuccess	What to do after successful execution: archive, keep, or delete

HTTP commands support method, url, headers, and body. All string values support placeholder substitution (see below).

CLI commands support program, args (string array), and workingDirectory.

Actions can also be placed inside section blocks to scope them to a specific part of the entry.

Command placeholders (resolved in this order):

1. {{param.NAME}} — runtime user input from the action's parameters form.
2. {{content.self}} / {{content.ID}} / {{entry.FIELD}} — data pulled from the entry itself at execution time. content.self is the block that owns a section action; content.ID targets a block by its id; entry.FIELD is one of title, subtitle, type, id, source, severity, tags. Because inline edits persist to the entry, these expand to the edited text — so editing a comment then clicking Approve/Submit uses the edited version.
3. {{VAR}} — secrets from actionview.json's secrets map (or an environment variable).

Actions run as background jobs. Clicking an action returns immediately; the command runs server-side while the button shows live progress (spinner, elapsed timer, streamed output, Cancel). On success the entry follows onSuccess (archive/keep/delete). Every run is recorded in the entry's activity log with its command, exit code, duration, and output.

Parameterized Actions

Some actions need user input — for example, posting a PR review comment whose draft was written by an AI but should be editable before sending. Declare the inputs as parameters:

{
  "label": "Post Comment",
  "style": "primary",
  "parameters": [
    {
      "name": "body",
      "label": "Comment",
      "type": "multiline",
      "default": "Consider making CacheTTL configurable...",
      "required": true,
      "helpText": "Edit before posting."
    }
  ],
  "command": {
    "type": "http",
    "method": "POST",
    "url": "https://api.github.com/repos/acme/backend/pulls/482/comments",
    "headers": { "Authorization": "Bearer {{GITHUB_TOKEN}}" },
    "body": { "body": "{{param.body}}" }
  },
  "onSuccess": "keep"
}

When parameters is present the UI expands an inline form under the button (textarea, select, number, boolean, or single-line text). The user's input is substituted into the command via {{param.NAME}} placeholders.

Parameter field	Description
name	Identifier used as {{param.NAME}}. Must match [A-Za-z_][A-Za-z0-9_]*.
label	Field label shown in the form.
type	text, multiline, select, number, or boolean. Defaults to text.
default	Initial value (e.g. an AI's draft). For numeric/boolean fields the string is parsed.
options	Allowed values when type is select.
required	If true, a non-empty value must be supplied before execution.
placeholder	Placeholder text inside the input.
helpText	Help text shown beneath the input.

Substitution rules:

• {{param.NAME}} is resolved first, then {{content.*}}/{{entry.*}}, then {{SECRET}} — separate namespaces, so user input cannot collide with secret names.
• A parameter default may itself contain a content reference (e.g. "{{content.self}}") to pre-fill the form from a block's current (possibly edited) text without duplicating it.
• Inside a JSON body, substitution happens at the string-leaf level — special characters in user input (quotes, backslashes, newlines) are JSON-escaped automatically and cannot break the payload.
• Drafts are persisted to localStorage per entry+action, so a SignalR refresh while you're editing won't wipe your work.

Data Directory Layout

data/
  inbox/     # Drop zone for new entry files
  active/    # Validated entries currently shown in the dashboard
  archive/   # Completed or dismissed entries with outcome metadata
  errors/    # Invalid entries with .error.txt companion files

Samples

The samples/ directory contains example entries demonstrating different use cases:

• deploy-approval.json -- production deployment approval workflow with pre-deployment checks
• incident-rca.json -- incident root cause analysis review with config diffs and action items
• pr-review.json -- pull request review with code blocks, AI analysis, and review actions

Try them out:

cp samples/deploy-approval.json data/inbox/

Project Structure

actionview.json              # Configuration
schemas/
  entry.v1.schema.json       # Entry JSON schema
samples/                     # Example entry files
src/
  ActionView.slnx            # .NET solution file
  ActionView.Core/           # Shared models and services
  ActionView.Cli/            # CLI tool (actionview)
  ActionView.Api/            # Web server (actionview-server)
  ActionView.Mcp/            # MCP server (actionview-mcp)
  ActionView.Tests/          # Test suite
  client/                    # React + TypeScript dashboard (Vite)