convez.ai
MCP Server
allcolor

PawFlow-Agents

allcolor/PawFlow-Agents

Ver no GitHub
BomPluginScore · de 0 a 100

PawFlow (Platform for Agentic Workflows) Self-hosted agent runtime for real infrastructure. Run durable AI agents against your own files, tools, browsers, desktops, services, and workflows with relay-backed execution, shared context, multi-provider agents, and deterministic flows.

Instalação

$npx convez-ai allcolor/PawFlow-Agents

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
26
Forks
3
Acompanhando
0
Saúde
71%
Último commit
há 1 dia
Versão
1.0.0-beta.332
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.


PawFlow is the runtime layer between chat agents, local tools, and production workflows. The server keeps conversations, context, memory, files, flows, and provider sessions durable. Relays execute filesystem, shell, browser, desktop, and media tools next to the machines where the work actually happens.

Use it when a hosted coding assistant is too boxed-in, a workflow tool is too rigid, and a library is not enough runtime.

Why PawFlow

PawFlow gives agents a real operating surface without handing your workspace to a vendor-controlled agent cloud.

  • Relay-backed tools: read, edit, grep, run commands, browse, control desktops, generate media, and inspect projects through explicit relay routes.
  • Durable context: conversations, shared context, per-agent context, memory, knowledge graphs, diaries, project graphs, files, and buckets survive restarts.
  • Multi-provider agents: mix Codex app-server, Claude Code, Antigravity/Agy, Gemini CLI, Anthropic, OpenAI, and OpenAI-compatible services per agent or conversation.
  • Shared clients: continue the same conversation from the web UI, PawCode CLI, VS Code, API clients, or channel integrations.
  • Deterministic flows: turn repeated work into NiFi-style DAGs with scheduling, backpressure, checkpoints, approvals, and explicit LLM steps.
  • Package ecosystem: distribute agents, skills, tools, services, flow tasks, flows, and UI extensions as signed .pfp packages or import skills from supported marketplaces.

What You Can Build

  • Agentic coding sessions against a linked workspace, with persistent context and auditable tool output.
  • Multi-agent operations where planners, coders, reviewers, researchers, and verifiers work in the same conversation.
  • Browser and desktop automation for workflows that do not have clean APIs.
  • Media pipelines that create images, video, audio, 3D assets, voice, and FileStore outputs.
  • Scheduled operational flows: daily digests, inbox triage, data transforms, reports, monitoring, and webhook-driven automation.
  • Reusable packages and registries for sharing internal or community agents, skills, tools, services, flow tasks, flows, and UI extensions.
  • Portable conversations with full PawFlow archives, including optional FileStore attachments and generated files.

Quick Start

The easiest path is the Docker installer from the latest release. It starts PawFlow, opens the bootstrap wizard, creates the first admin user, configures the selected LLM services, deploys the starter flow, and opens your first agent conversation.

Docker Installer

Downloadable artifacts are published on the latest GitHub release: installer zip, PawCode packages, Relay CLI archives, Relay Desktop installers, checksums, and source archives.

PAWFLOW_VERSION=$(curl -fsSL https://api.github.com/repos/allcolor/PawFlow-Agents/releases/latest \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["tag_name"])')

curl -L -o "pawflow-install-$PAWFLOW_VERSION.zip" \
  "https://github.com/allcolor/PawFlow-Agents/releases/download/$PAWFLOW_VERSION/pawflow-install-$PAWFLOW_VERSION.zip"
unzip "pawflow-install-$PAWFLOW_VERSION.zip"
cd "pawflow-install-$PAWFLOW_VERSION"

bash scripts/install-pawflow.sh --port PORT --pull-images --version "$PAWFLOW_VERSION"

On Windows PowerShell with Docker Desktop Linux containers, use the bundled PowerShell installer instead:

powershell -ExecutionPolicy Bypass -File scripts/install-pawflow.ps1 -Port PORT -PullImages -Version $env:PAWFLOW_VERSION

Check and apply release updates with:

bash scripts/install-pawflow.sh --check-updates
bash scripts/install-pawflow.sh --self-update
bash scripts/install-pawflow.sh --version NEW_VERSION --port PORT --pull-images

The update command recreates the PawFlow server container on the requested image while keeping persistent data under PAWFLOW_HOME, then removes older PawFlow server/relay image tags unless --keep-old-images is set.

Open the installer at:

https://localhost:PORT/install

The first-run Private Gateway key is RoyBetty. Finalizing the wizard replaces it.

From Source

git clone https://github.com/allcolor/PawFlow-Agents.git
cd PawFlow-Agents
pip install -r requirements.txt
python cli.py start --host 0.0.0.0 --port PORT

Open the web chat at:

http://localhost:PORT/chat

Clients

Web UI

The web UI is the main operator surface: chat, context editor, memory editor, file attachments, relay tools, desktop entry points, terminals, provider sessions, and flow actions in one place.

PawCode CLI

PawCode is a terminal client for the same PawFlow conversations. It can be used interactively or in Claude Code-compatible stream-JSON mode.

pawcode --server http://localhost:PORT

echo '{"type":"user","message":{"role":"user","content":"hello"}}' | \
  pawcode --input-format stream-json --output-format stream-json

VS Code and Relays

Use the relay CLI or Relay Desktop to connect workspaces, desktops, browsers, and terminals. The VS Code extension can attach to the same conversation and resource panel.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        PawFlow Server                           │
│                                                                 │
│  ┌──────────┐  ┌──────────┐  ┌─────────┐  ┌────────────────┐  │
│  │  Agents  │  │ Pipeline │  │   Auth   │  │  Web Chat UI   │  │
│  │  (LLM +  │  │  Engine  │  │ Gateway  │  │  (SSE, files,  │  │
│  │  tools)  │  │ (100+    │  │ (9 OAuth │  │   context,     │  │
│  │          │  │  tasks)  │  │ provid.) │  │   commands)    │  │
│  └────┬─────┘  └──────────┘  └──────────┘  └────────────────┘  │
│       │                                                         │
│  ┌────┴─────────────────────────────────────────────────────┐  │
│  │              90+ Tool Handlers (via relay)                │  │
│  │  bash, read, write, edit, glob, grep, web_search,        │  │
│  │  screen, browser, generate_image, generate_video,        │  │
│  │  generate_audio, generate_3d, clone_voice, speak,        │  │
│  │  remember, kg_add, project_graph, delegate, plans, ...   │  │
│  └──────────────────────────┬───────────────────────────────┘  │
│                             │ WebSocket                        │
└─────────────────────────────┼──────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │   Relay (Docker)   │  ← runs on user's machine
                    │   or native host   │
                    └───────────────────┘

The server hosts the API, agent orchestration, pipeline engine, and web UI. A relay runs on the user's machine (or in a Docker container) and executes tools — filesystem access, bash commands, code edits — over a WebSocket connection. This means agents can manipulate your local codebase without the server needing direct access to your files.

LLM Providers

ProviderModeFeatures
Claude CodeCLI subprocess/container + MCPNon-interactive coding turns, session persistence, thinking
Claude Code interactiveInteractive CLI container + observed streamClaude subscription sessions, live control, provider-observed usage
Codex app-serverApp-server protocol in pooled containerCodex subscription or OpenAI API-key coding agents, threads, steering
Antigravity / AgyInteractive CLI container + observed streamDefault Gemini subscription provider, Gemini OAuth pool, MCP tools
Gemini CLICLI subprocess/containerSecondary Gemini CLI path for Pro/CLI-specific workflows
Anthropic APIDirect HTTPStreaming, tool use, vision, extended thinking
OpenAI APIDirect HTTPStreaming, tool use, vision, JSON mode
OpenAI-compatibleDirect HTTPLocal/self-hosted and third-party compatible endpoints via base_url

Switch providers per agent, per conversation, or globally. API keys normally use direct openai/anthropic services; subscription logins use the matching CLI-backed provider (codex-app-server, claude-code-interactive, or antigravity-interactive). Self-hosted and third-party LLMs can use the OpenAI-compatible endpoint (base_url override). See LLM Providers.

Agent Capabilities

Cognitive Systems

Agents have persistent memory that survives across conversations:

SystemPurposeStorage
MemoryFacts, preferences, events organized in wing/hall/room taxonomydata/memories/{user}.json
Knowledge GraphEntity-relationship triples with temporal validitydata/knowledge_graphs/{user}.json
Agent DiaryPersonal observations, decisions, learnings per agentdata/memories/{user}/diary_{agent}.jsonl
Project GraphAST-based code structure graph (17 languages via tree-sitter)data/graphs/{user}/{conv}/graph.json

Memory digests and diary entries are automatically injected into the system prompt.

Multi-Agent

  • Delegate tasks to sub-agents with delegate()
  • Each sub-agent gets its own LLM, tools, and conversation context
  • Agents can run in parallel or sequentially
  • Git worktree isolation for parallel coding tasks is on the roadmap

Plans

  • Create structured multi-step plans with create_plan()
  • Step-by-step execution with approval gates
  • Assign steps to different agents
  • Verify completed work before moving on

Pipeline Engine

100+ tasks across 5 categories for data processing workflows:

CategoryCountExamples
System11+log, wait, executeScript, cronTrigger, listFiles
IO50+HTTP, Telegram, Discord, Slack, WhatsApp, S3, GCS, Azure, SFTP, Kafka, MQTT, email, chat UI, relay
Data25+transformJSON, inferLLM, executeSQL, compressContent, validateJSON, Avro/Parquet
Control10+routeOnAttribute, splitContent, mergeContent, controlRate, subflows, wait/notify
AI2+agentLoop, agentActions, tool-use cycle

Flows are defined in JSON, executed as DAGs, and support backpressure, checkpointing, crash recovery, parameter contexts, subflows, and CRON scheduling.

Packages and Marketplace

PawFlow Packages (.pfp) are signed zip artifacts for distributing PawFlow resources. A package can include agents, prompts, skills, themes, task definitions, flows, service definitions, tools, service providers, flow tasks, task providers, and UI extensions. Install is review-first: PawFlow verifies the package signature and lock file, shows a selectable install plan, records per-object provenance, and executes code-bearing objects through a relay runtime instead of importing third-party code into the server process.

Common package workflows:

/pfp key-create
/pfp build ./my-package.pfpdir --key-env PAWFLOW_PFP_SIGNING_KEY
/pfp inspect ./dist/my-package-1.0.0.pfp
/pfp install ./dist/my-package-1.0.0.pfp --include skill:x,service_provider:y
/pfp dev-load ./my-package.pfpdir --include service_provider:image --secret api_key=my_provider_key
/pfp export --package my.bundle --version 0.1.0 --include agent:helper,flow:daily --out ./my.bundle.pfpdir

Marketplace and registry support is decentralized. Users can add static package registries, search them, inspect remote packages with explicit download confirmation, then install or update selected objects. Skill marketplace import is also supported for Codex/OpenAI skills, Claude/Anthropic plugin marketplaces, HermesHub, and OpenClaw GitHub tree URLs; imports are bounded, reviewed, and never grant tool permissions automatically.

See PawFlow Packages, PFP Developer Guide, PFP Publisher Guide, and Marketplace.

Expression Language

40+ chainable operations for dynamic configuration:

${name:upper}                                     → "ALICE"
${api_key:default("not-set")}                      → uses fallback if empty
${status:equals("active"):then("ON"):else("OFF")}  → conditional logic
${csv_line:split(","):index(0):trim}               → first CSV field, trimmed
${response:json_get("data.items.0.id")}             → extract from JSON
${content:hash_sha256}                              → hash a value
${:uuid}                                            → generate a UUID
${:now:format("yyyy-MM-dd")}                         → "2026-04-08"

Expressions resolve through a cascade: secrets → flow parameters → conversation → user → global → environment variables. See Expression Language docs for the full reference.

Web Chat

  • Real-time streaming via SSE
  • Shared conversations across web, PawCode CLI, VS Code, API clients, and channel flows
  • File explorer with relay filesystem access
  • Context editor (view/edit agent context)
  • Conversation management with auto-titles
  • Drag & drop file attachments and FileStore outputs
  • 60+ slash commands (/agent, /memory, /relay, /run, /plan, /desktop, ...)
  • Desktop/VNC entry points plus relay-backed screen actions
  • Escape key: 1x = graceful interrupt, 2x = force stop
  • Multi-agent with agent switching

Authentication

9 OAuth providers out of the box:

ProviderStatus
Built-in (username/password)Ready, tested
Generic OAuth2Ready, tested
GoogleReady, tested
GitHubReady, tested
X (Twitter)Ready, tested
TelegramReady, tested
MicrosoftReady, not tested
FacebookReady, not tested
AmazonReady, not tested

Configuration

Agents, services, and flows are configured via JSON. Parameters cascade: flow → conversation → user → global.

{
  "llm_service": "claude_code_llm_service",
  "summarizer_service": "claude_code_llm_service",
  "permission_mode": "auto",
  "max_iterations": 200
}

See .env.example for environment variables.

Tests

pytest tests/ -v    # 2500+ tests across 100+ test files

Documentation

DocumentDescription
ArchitectureInternal architecture, FlowFile, components
Agent SystemAgent loop, context, plans, multi-agent, streaming
Cognitive ToolsMemory, KG, diary, project graph (21 tools)
Expression Language40+ operators, scopes, cascade
Slash CommandsAll webchat commands
LLM ProvidersOpenAI, Anthropic, Claude Code, Codex app-server, Antigravity/Agy, Gemini CLI, compatible APIs
PawCode CLITerminal client and stream-JSON mode
VS Code ExtensionEditor client and resource panel
Multi-Client ConversationsShared runtime across web, CLI, VS Code, API, channels
Desktop/VNCnoVNC desktop, screen tool, audio notes
Media ToolsImage/video/audio/3D/voice tools
Tool CatalogAgent-facing tools
Services CatalogService types and provider integrations
Task CatalogBuilt-in flow tasks and tool tasks
PawFlow PackagesSigned .pfp packages, install plans, registries, export/build, and security model
PFP Developer GuideLocal package development with dev-load, service providers, flow tasks, media artifacts, and SDK patterns
PFP Publisher GuideRegistry publishing, versioning, SHA pinning, and key rotation
MarketplacePFP registries, skill marketplace import, review model, and UI/CLI entry points
Security ModelTrust boundaries and production checklist
DeploymentLocal, Docker, production
DockerDocker setup, relay mode
FilesystemRelay, backends, permissions
DevelopmentCreating custom tasks/services

Roadmap

See ROADMAP.md for the full roadmap.

Key upcoming areas:

  • Stabilization and release hardening
  • Manual flow editor
  • New media service providers
  • Git worktree isolation for parallel agents
  • Mobile client (PWA)
  • MCP elicitation and PawFlow as an MCP server
  • Filesystem hooks
  • Full cost tracking dashboard

Contributing

See CONTRIBUTING.md. In short:

  1. Fork & clone
  2. pip install -r requirements.txt
  3. Make changes, run pytest tests/
  4. Open a PR

License

MIT

Ver o original no GitHub

Bom para

Relacionados