aphelion

Aphelion

The local flight recorder for AI agents working on WordPress.

Agents already operate WordPress sites. Aphelion records every move into an append-only trail on your machine, rendered three ways: a real-time map of the work, a replay of any moment, and an audit trail that proves what actually changed.

What makes the record trustworthy:

• One file is the truth. A session is a single append-only JSONL file, flushed to disk on every event and readable only by you, with optional SHA-256 hash chaining (--integrity) that makes tampering detectable. The live board, replay, and timelapse all render this one file, so there is no second history to diverge.
• Nothing leaves your machine. The board binds to 127.0.0.1, there is no account and no telemetry, and no recording is ever deleted for you.
• Agents are observed, never touched. aphelion mcp -- <server> passes agent traffic through byte for byte while recording what they declare: tool names and argument keys, never values, content, or credentials.
• It speaks WordPress. Block edits belong to their page, revisions to their post, plugin settings to their plugin, and every card carries a name a site owner can read. Idle sessions close on their own; a stale observer warns instead of quietly missing events.
• Zero runtime dependencies. Node 20 or newer is the whole install.

Quickstart

npm install --global aphelion
cd /path/to/your-project
aphelion --open

The command prints the local board URL and trail path. Keep it running while an agent works. Project-local works too: npm install --save-dev aphelion && npx aphelion --open.

Record once, render many

agent hooks ─┐
repo watcher ├─> append-only trail ─> live board
WordPress ───┤                     ├─> replay
WP-CLI/MCP ──┘                     └─> timelapse

Every surface is a projection of one JSONL trail — no view owns a second history. The board speaks three nouns: places (durable WordPress objects, the only things with a position), flows (channels carrying an actor's work), and changes (timed claim-plus-confirmation moments in a place's history). The full contract lives in the topology language; evidence stays structural — block and attribute names, never content, option values, credentials, or Ability payloads.

Add WordPress evidence

Repository observation needs no WordPress installation. Site context is progressive:

Level	Install cost	What becomes visible
Repo watcher and agent hooks	None	Files, declared actions, plan progress, presence
Generic MCP stdio tap — aphelion mcp -- <server command...>	None; wraps an existing local MCP server	MCP presence, tool-call names, structural argument keys, and declared completion without values or result bodies
Read-only WP-CLI sidecar	A local WP-CLI / Docker / SSH command	Runtime baseline, drift fingerprints, site identity
Audit mu-plugin	One PHP file in wp-content/mu-plugins/	WordPress hook effects: posts, blocks, settings, terms, menus, users, comments, plugins
Plugin adapter	Optional	Product semantics beside the raw effect; Accelerate included

cp node_modules/aphelion/src/mu-plugin/aphelion-audit.php \
  /path/to/wordpress/wp-content/mu-plugins/aphelion-audit.php

aphelion \
  --site http://localhost:8081 \
  --audit-log /path/to/wordpress/wp-content/aphelion/audit.jsonl \
  --wp-command '["docker","exec","wordpress","wp","--allow-root","--path=/var/www/html"]' \
  --open

The mu-plugin has no settings screen and no remote transport (PHP 7.4+; WordPress-aware features target 6.9+). Full channel, transport, redaction, and timing contract: WordPress observation surfaces.

Run automatically — opt in

The normal command stays foreground and explicit. For a workstation or long-lived local stack, an OS user service can start Aphelion at login — deliberately not enabled by default: background observation should be a conscious choice. See Running Aphelion in the background for launchd/systemd --user setup, health checks, and removal.

CLI

Command	When to use it
aphelion [target]	Observe a repository; defaults to the current directory.
aphelion serve [target]	The explicit form of the default command.
aphelion sessions [target]	List recorded sessions and their trail paths.
aphelion timelapse <trail.jsonl>	Render a standalone timelapse from an existing trail.
aphelion hook	Relay one agent-hook payload from stdin to the local daemon.
aphelion mcp -- <server command...>	Transparently observe an existing MCP stdio server.

Option	Meaning
--open	Open the loopback board after startup.
--port <number>	Preferred loopback port; falls forward if occupied.
--idle-timeout <minutes>	End a session after this much non-heartbeat inactivity (default 30).
--site <url>	Record a site target instead of a repository target.
--audit-log <path>	Tail the site-local audit mu-plugin JSONL.
--debug-log <path>	Tail a WordPress debug log with capture-boundary redaction.
--wp-command <json>	Read-only WP-CLI baseline from a JSON string array; no shell evaluation.
--integrity	Add SHA-256 prev links to new trail events.
--no-watch	Disable repository filesystem watching.
--output <path>	Timelapse .html or .mp4 output path.

Agent hooks pipe straight in — printf '%s\n' "$AGENT_HOOK_JSON" | aphelion hook — and MCP calls stay declared requests, related to observed WordPress effects by request ID without ever merging the records.

Library

Aphelion is also a typed, zero-dependency ESM library:

import { createTrailWriter, projectEvents, renderTimelapse, startDaemon } from 'aphelion'

The package exports the trail reader/writer, reducer, replay index, daemon, sidecar, WordPress scanner, Accelerate adapter, and timelapse renderer, with type declarations.

Trail ownership and privacy

The trail is the audit record: append-only, owned by you, and durable enough to answer "what did the agent actually do" months after the session — replay is the forensic view of the same file the live board projected.

Property	Contract
Project trails	<repo>/.aphelion/trail/<session>.jsonl
Site trails	~/.aphelion/trails/<site-slug>/<session>.jsonl
File mode / flush	0600, flushed every event
Retention	Never deleted automatically
Network	Board and ingest bind to 127.0.0.1
Telemetry / accounts	None

Trails can still contain local paths, object titles, actor names, and action summaries — treat them as operational records and review before sharing. See Security.

Documentation

Documentation index · Topology language · Observation surfaces · Trail format · Background service · Releasing · Changelog

Development

npm install
npm run verify

The verification gate builds the board, checks JS and PHP syntax, validates docs, runs the unit and desktop/mobile browser suites, audits package exports, and installs the dry-run tarball into a blank consumer.

Aphelion adapts the declared-versus-observed model from sodiumsun/agenttrail (MIT, vendored at 41454d4); substantially adapted files retain provenance comments.

License

MIT. See LICENSE.