PawFlow-Agents: Instructions file for Claude Code

PawFlow — Development Context

What is PawFlow

PawFlow is a self-hosted AI agent orchestration platform inspired by Apache NiFi. It combines a data flow engine (FlowFile/Task/Service/Flow) with an LLM agent system that supports tool-use loops, multi-agent conversations, and streaming SSE.

Architecture

• Core: FlowFile (data unit), Task (processor), Service (connection), Flow (DAG)
• Engine: FlowExecutor (batch) + ContinuousFlowExecutor (queues/backpressure)
• Agents: AgentLoopTask with tool-use loop, multi-agent, streaming SSE
• Auth: AuthGatewayService with 9 OAuth providers
• Storage: ConversationStore (directory-based), MemoryStore, KnowledgeGraph, AgentDiary
• Relay: WebSocket reverse-tunnel for remote filesystem + tool execution
• CLI: PawCode (Claude Code drop-in replacement)

Key Conventions

• All documentation and code comments MUST be in English
• ALWAYS document new features, tools, tasks, services, and handlers — update the relevant file under docs/ in the same change
• ALWAYS write unit tests for new code — handlers, tasks, services, parsers; nothing ships without coverage
• Zero backward compatibility — migration is one-shot, delete old code
• No "anonymous" or "default" fallbacks — missing required params = ValueError
• Every message MUST have UUID + timestamp at creation
• selectedAgent is NEVER empty in a conversation
• Force stop = immediate kill, NOT an error, NEVER affects the next loop
• All actions are async — nothing blocks UI or HTTP worker
• Bugs are always our code — never blame cache/OS/libs first

Expression Language

${scope.key:op1:op2("arg")} — 40+ chainable operations. Resolution cascade: flow → conversation → user → global.

Tool Architecture

All filesystem tools extend BaseFsHandler and route through the relay service. Tools execute in the relay Docker container by default, on the host if local=true. No tool accesses the server filesystem directly (except internal storage: memories, KG, diary, graphs).