some-useful-agents

A local-first agent playground. Author agents as composable flows, run them from the CLI or MCP, schedule them on cron, chain them into multi-step pipelines with branching and loops, and manage everything from a web dashboard.

MIT-licensed. Published to npm.

What you get

• Agents as flows — each agent is a DAG of nodes. Nodes execute shell commands, Claude Code prompts, or named tools. Flow control (conditional, switch, loop, agent-invoke, branch, end, break) lets agents make decisions and orchestrate sub-agents. Full reference: docs/flows.md.
• Multi-provider LLM support — claude-code nodes can use Claude or Codex via the provider field. Stream-json progress tracking shows real-time turn status during execution.
• 10 built-in tools — shell-exec, claude-code, http-get, http-post, file-read, file-write, json-parse, json-path, template, csv-to-chart-json. Plus MCP-imported tools and user-authored tools. Full catalog: docs/tools.md.
• MCP servers as first-class — paste a Claude Desktop / Cursor mcpServers config, sua discovers the tools, you pick which to import, and runs can call them like any other tool. Enable/disable/delete whole servers from /settings/mcp-servers. Full guide: docs/mcp.md.
• Output widgets — render run output as structured UI. Four built-in widget types (raw, key-value, diff-apply, dashboard) plus ai-template with an HTML grammar that supports {{outputs.X}}, {{#each}}, {{#if}} / {{#unless}} truthy conditionals, and sandboxed <iframe> from a small host allowlist (YouTube + Vimeo). Inline widget controls (replay, field-toggle, view-switch) drive interactivity from URL params with no client JS. Full reference: docs/output-widgets.md.
• Widget packs — bundles of curated agents and dashboards that install as a unit. The bundled Starter pack ships three demo agents organised into Media + Weather dashboards. Browse + install at /packs; pack uninstall removes the dashboards but keeps the agents (reference-only ownership).
• Dashboards — named, ordered, sectioned views over installed agents. Pack-owned (e.g. starter:media) or user-created. Inline editor at /dashboards/:id/edit — add/remove/reorder sections and tiles, all server-rendered. The default dashboard at /pulse is auto-derived from per-agent pulseVisible flags.
• Dashboard — web UI for managing agents, tools, runs, secrets, variables, MCP servers, packs, and Pulse tiles. Visual DAG editor, click-to-replay, YAML editor, template palette autocomplete, per-node action dialogs, live preview for output widgets. Full tour: docs/dashboard.md.
• Build from a goal, with a critic loop — describe what you want in plain language; the built-in build-planner proposes a complete plan (new agents, dashboard sections, references to existing agents). A structural critic checks the plan against catalog reality before showing it to you and re-fires the planner with feedback up to twice if the first pass has issues. After 2 retries you get a "Commit anyway" override. Telemetry at /metrics/planner tracks first-attempt-clean rate, retry counts, and commit rate.
• AI suggest improvements — one-click agent analysis via the built-in agent-analyzer. Reviews your agent's YAML, classifies changes, shows a colored diff, and auto-validates + fixes the suggested YAML before presenting it.
• Global variables — plain-text, non-sensitive values available to every agent. CRUD via /settings/variables or sua vars CLI. Referenced as $NAME in shell, {{vars.NAME}} in prompts.
• MCP server (outbound) — expose your agents to Claude Desktop and other MCP clients over HTTP/SSE.
• Secrets store — passphrase-encrypted at rest (scrypt N=2^17). Dashboard CRUD with copy-before-save modal and 3-layer redaction.
• Scheduling — cron expressions on any agent. Temporal provider available for durable workflows.
• 15 bundled examples — from "hello world" to MCP-driven graphics generation. Auto-installed on sua init.

Quick start

npm install -g @some-useful-agents/cli
mkdir my-agents && cd my-agents
sua init                    # creates project + installs example agents
sua workflow run hello      # run your first agent
sua dashboard start         # open the web dashboard

Prefer npx? npx @some-useful-agents/cli@latest init works without installing globally.

Example agents

Installed automatically by sua init. Manage with sua examples install/remove/list.

Agent	What it teaches
hello	Your first agent, single shell node
two-step-digest	Chain nodes with dependsOn + upstream output passing
daily-greeting	Cron scheduling (schedule: "0 8 * * *")
parameterised-greet	Agent inputs with defaults (--input NAME=Greg)
conditional-router	Flow control: conditional + onlyIf + branch merge
research-digest	Agent-invoke + loop (nested sub-flows)
daily-joke	HTTP tool fetching from icanhazdadjoke.com
parameterised-greet-claude	Claude Code companion (requires API key)
llm-tells-a-joke	Configurable topic input + clean prompt design
agent-analyzer	Self-correcting 3-node pipeline: analyze, validate, fix
agent-builder	Goal-driven wizard, builds agents from plain language
system-health	Disk/memory/CPU check with Pulse metric tile
daily-summary	Activity summary with Pulse text-headline tile
graphics-creator-mcp	Chains 5 modern-graphics MCP tools: theme → render → composite
chart-creator-mcp	CSV → csv-to-chart-json builtin → chart render via MCP

CLI commands

Agents

sua agent list                          # all agents (examples + local)
sua agent new                           # interactive scaffold
sua agent run <name>                    # run once
sua agent run <name> --input K=V        # supply inputs
sua agent reimport <path>               # refresh agent(s) in DB from on-disk YAML

Workflows (DAG agents)

sua workflow list                       # DAG agents in the store
sua workflow run <id>                   # execute a flow
sua workflow replay <runId> --from <nodeId>  # replay from a node
sua workflow import-yaml <file>         # import a v2 YAML into the store

Tools

sua tool list                           # built-in + user tools
sua tool show <id>                      # inspect inputs/outputs
sua tool validate <file>                # schema-check a tool YAML

Examples

sua examples install                    # import all bundled examples
sua examples remove                     # remove example agents from DB
sua examples list                       # show install status

Variables

sua vars list                           # all global variables (names + values)
sua vars get <NAME>                     # get a variable's value
sua vars set <NAME> <VALUE>             # set/update a variable
sua vars delete <NAME>                  # remove a variable

Secrets

sua secrets set <NAME>                  # store an encrypted secret
sua secrets list                        # list names (values hidden)
sua secrets delete <NAME>               # remove a secret

Build planner

sua planner smoke                       # dry-run preview of pipeline scenarios
sua planner smoke --live                # run all 6 server scenarios end-to-end
sua planner smoke --live --browser      # also drive 2 wizard scenarios via playwright

Infrastructure

sua init                                # initialize a project
sua doctor                              # check prerequisites
sua mcp start                           # start the MCP server
sua dashboard start                     # start the web dashboard
sua daemon start                        # run dashboard + scheduler + MCP detached
sua schedule list                       # show scheduled agents

Dashboard

Start with sua dashboard start. Dark mode by default, JetBrains Mono, warm stone neutrals.

• Pulse — information radiator at /pulse, the default dashboard. Signal tiles show agent output as live widgets. 10 display templates including widget (mirrors the agent's own outputWidget schema). Drag-and-drop reorder, widget palette with auto-theming, system metric tiles, markdown rendering, YouTube media player, tile collapse/expand. A switcher dropdown at the top of the page lets you flip between Default and any installed pack/user dashboard. "Hide all" / "Show all" buttons bulk-toggle every signal — useful before installing a pack.
• Packs — /packs lists all registered packs (bundled + user-created), shows install state, and routes Install/Uninstall through one click. Built-in packs ship in packages/core/packs/*.yaml and auto-register on daemon start.
• Dashboards — render at /dashboards/:id, edit at /dashboards/:id/edit. Pack-owned dashboards are editable (rename, reorder, add/remove tiles) but not deletable; uninstall the pack instead. User-created dashboards are deletable. Create a new one from the dropdown's "+ New dashboard name" input.
• Build from goal — Build button on the home page (/) and /agents. Describe what you want in plain language. The build-planner proposes a complete plan: new agents, dashboard sections, and references to existing agents you already have. A structural critic validates the plan before showing it to you and silently re-fires the planner with feedback if the first pass has issues. Review the generated YAML before saving; "Commit anyway" lets you override unresolved warnings.
• Schedule editor — /agents/<id>/config has a Schedule card so you can set or clear a cron expression without hand-editing YAML. Server-side validation rejects invalid expressions and sub-minute cadences (unless the agent opts in via allowHighFrequency: true).
• Agents — card grid with User / Examples / Community tabs, per-tab counts, filtering (status, search), sorting, pagination. 5-tab detail page: Overview (DAG viz, stats), Nodes (edit/delete/add), Config (variables, output widget, signal, secrets), Runs (history), YAML (editor).
• Output widget editor — at /agents/:id/config, pick from visual cards (raw / key-value / diff-apply / dashboard / ai-template), load one of 5 starter examples in one click, watch a live preview rerender as you edit. Full reference: docs/output-widgets.md.
• Tools — browse User / Built-in tabs with per-tab counts, filtering, pagination. Paste a Claude-Desktop-style config at /tools/mcp/import to import MCP servers wholesale.
• Settings → MCP Servers — list of imported MCP servers with tool counts, enable/disable toggle, cascade delete.
• Suggest improvements — AI-powered agent review with "Apply now" one-click save. Auto-fixes shell template mistakes. Available from failed run pages with the error pre-filled.
• Runs — filter by agent/status, paginate, replay from any node, resolved variables panel, real-time turn progress for LLM nodes.
• Settings — secrets CRUD with passphrase unlock, global variables, MCP servers, MCP token rotation.
• Tutorial — 8-step guided walkthrough that scaffolds agents and culminates in installing the bundled Starter pack.

Flow control

Agents support first-class flow control nodes:

nodes:
  - id: fetch
    type: shell
    command: echo '{"status": 200, "data": "ok"}'

  - id: check
    type: conditional
    dependsOn: [fetch]
    conditionalConfig:
      predicate: { field: status, equals: 200 }

  - id: process
    type: shell
    command: echo "Processing..."
    dependsOn: [check]
    onlyIf: { upstream: check, field: matched, equals: true }

  - id: fallback
    type: shell
    command: echo "Fetch failed"
    dependsOn: [check]
    onlyIf: { upstream: check, field: matched, notEquals: true }

Available node types: conditional, switch, loop, agent-invoke, branch, end, break.

Security

• Secrets encrypted at rest — AES-256-GCM with scrypt KDF (OWASP 2024 params)
• 3-layer redaction in run logs — declared secrets, sensitive name patterns (TOKEN, KEY, PASS), known credential value patterns (GitHub PATs, AWS keys, JWTs)
• Path traversal protection — file-read/file-write tools validate paths stay within the working directory
• Env-var injection deny-list — agent inputs cannot override LD_PRELOAD, PATH, NODE_OPTIONS, or 25+ other sensitive env vars
• MCP binds localhost — bearer token auth, loopback-only by default, timing-safe token comparison
• Community shell gate — community agents require explicit --allow-untrusted-shell
• Dashboard auth — 3-layer (Host + Origin + cookie), HttpOnly SameSite=Strict cookies, 8-hour expiry
• CI/CD — SHA-pinned GitHub Actions, npm Trusted Publishing via OIDC (no static NPM_TOKEN)
• Example agents vetted — CI security check + execution test on every PR

Full model: docs/SECURITY.md

Packages

Package	Description
@some-useful-agents/core	Types, schemas, stores, executor, tools, secrets
@some-useful-agents/cli	CLI commands, tutorial, scaffolding
@some-useful-agents/dashboard	Web dashboard (Express, server-rendered HTML)
@some-useful-agents/mcp-server	MCP server (HTTP/SSE transport)
@some-useful-agents/temporal-provider	Temporal worker for durable workflows

Requirements

• Node.js >= 22.5.0
• macOS or Linux (Windows untested)
• Docker (optional, for Temporal or docker-stdio MCP servers)

Documentation

• Quickstart — 30-minute first-touch guide
• Agents — YAML reference: inputs, nodes, schedule, signal, output widget
• Flows — conditional, switch, loop, agent-invoke, branch, end, break
• Tools — built-in tools, MCP tools, user-authored tools
• MCP servers — import, enable/disable, lifecycle
• Output widgets — widget types, field mapping, AI templates
• Templating — {{inputs.X}}, {{upstream.X.result}}, {{vars.X}}
• Dashboard tour — every page, what it's for
• Security model — threat model, secrets, sanitizer, MCP trust
• Architecture decisions — MADR-lite records for load-bearing choices

License

MIT