agentic-surfaces

A small, local-first workflow engine for running deterministic, agent-in-the-loop automations against your "surfaces" (Jira / Confluence / GitHub / HTTP APIs). Workflows are plain YAML: deterministic nodes (task.http, task.transform, task.branch, task.foreach, cache) do the wiring, and agent.run nodes call a Claude agent to decide or draft — with a live dashboard.

Repo & full docs: https://github.com/dalebaldwin/agentic-surfaces

Quick start

# point it at a folder containing agentic-surfaces.config.yaml + workflows/
npx -y agentic-surfaces start ./my-project --ui

• --ui serves a live dashboard at http://127.0.0.1:4000 (workflow graph, runs, agent activity, cache inspector).
• --watch restarts on config changes (use under a supervisor for live editing).
• Cron-triggered workflows fire on schedule; entry workflows are runnable from the dashboard.

Secrets

Workflows reference secrets as ${VAR}. Provide them however you like:

• a .env file in the working directory (auto-loaded), e.g. JIRA_EMAIL=…, or
• a secrets manager such as Doppler (doppler run -- npx agentic-surfaces …), or
• plain exports.

Real environment variables and Doppler override a .env.

Capabilities (plugins / skills)

A full agent's plugins and skills are declared config, not discovered from your ~/.claude. Set them in agentic-surfaces.config.yaml (project-wide) or per agent (frontmatter); the engine loads them and resolves plugin paths relative to the project dir, so capabilities can be vendored:

capabilities:
  plugins: [{ path: ./plugins/superpowers }]   # resolved against the project dir
  skills: all                                   # or a curated list, e.g. [office-hours, cso]
  settingSources: [project]                     # which .claude tiers load; [] = isolated

Play / pause + token metrics

• Play/Pause — the dashboard has a platform-wide pause toggle (also POST /api/pause|resume). When paused, scheduled cron workflows stop firing (in-flight runs finish; manual runs still work). It's file-backed (.flow-paused), so it survives a --watch restart.
• Token usage — each agent run records its tokens (input/output/cache) + cost; the dashboard shows a per-run total in the Runs panel and a per-node breakdown in the node drawer.

Safety

Set dryRun: true in agentic-surfaces.config.yaml to block + log all writes (deterministic HTTP writes and capable agents' tool/MCP writes) while you build. Flip to false to go live.

Packages

This is the launcher for the @agentic-surfaces/* toolkit (cli, core, agent, server, connectors). MIT licensed.