johnlindquist / johnlindquist/mdflow

feat: Run agents directly from URLs

Open
#5 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
604
Forks
43
PR merge metrics
No merged PRs in 30d

Description

Summary

Allow running agent markdown files directly from URLs, converting web-hosted instructions into executable agents via into.md.

Proposed Usage

# Run an agent hosted on a gist
ma https://gist.github.com/user/abc123

# Run an agent from a documentation site
ma https://example.com/agents/code-reviewer.html

# Run from a raw markdown URL (no conversion needed)
ma https://raw.githubusercontent.com/user/repo/main/AGENT.md

How It Would Work

  1. Detect if the file argument is a URL (already partially implemented in src/remote.ts)
  2. If URL ends in .md or is a raw content URL, fetch directly
  3. Otherwise, pipe through into.md to extract markdown from HTML
  4. Parse frontmatter and execute as normal
  5. Clean up temp file after execution

Use Cases

  • Shared Agents: Team shares agent definitions via gists or wikis
  • Agent Marketplace: Community-published agents runnable by URL
  • Documentation-as-Agent: Tutorial pages that are also executable
  • No-Install Distribution: Share an agent without requiring git clone

Security Considerations

  • Warn user when running remote agents (already implemented: printRemoteWarning)
  • Consider --trust-remote flag for CI/automation
  • Sandbox by default? Show frontmatter before execution?

Implementation Notes

  • Extend src/remote.ts to use into.md for HTML pages
  • Detect content type from response headers
  • Cache remote agents locally with TTL?

Questions for Discussion

  • Should we require explicit --remote flag for safety?
  • How to handle authentication for private gists/repos?
  • Should converted HTML agents be cached?

Related

This is part of exploring into.md integration opportunities.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading src/remote.ts and the existing printRemoteWarning flow. Trace how URL arguments are detected and how fetched content becomes an executable agent, then determine how into.md should handle non-Markdown pages. Done means supported remote URLs can be fetched, parsed, executed, and cleaned up while preserving the existing remote warning behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.