porki 0.3.0

Agentic orchestration.

porki

Table of Contents

1. Description
2. Quickstart
   • 2.1 Install
   • 2.2 Simple Command
3. Installation
   • 3.1 Prerequisites
   • 3.2 PyPI
   • 3.3 From Source
   • 3.4 Development Only (uv)
4. Test
5. CLI Reference

---

Description

porki is an agentic orchestration runtime for multi-agent workflows. It coordinates orchestrator and agent processes, persists shared state in Redis, and uses an LLM CLI (claude or codex) to plan and execute tasks.

It leverages markdown-based control files: a primary INSTRUCTIONS.md for orchestrator/agent directives and per-agent heartbeat markdown files for live control signals (for example pause/resume-style runtime directives).

Example usage: Systemg Orchestrator

[!WARNING] Designed to run with systemg.

Quickstart

Install

pip install porki

Simple Command

porki --help

Minimal runtime example (orchestrator + agent) with bundled test assets:

porki \
  --role orchestrator \
  --instructions tests/assets/INSTRUCTIONS.md \
  --llm-provider codex \
  --llm-cli codex

porki \
  --role agent \
  --instructions tests/assets/instructions/agent-research.md \
  --heartbeat tests/assets/instructions/heartbeat/agent-research.md \
  --agent-name agent-research \
  --goal-id goal-demo \
  --llm-provider codex \
  --llm-cli codex

By default, --redis-url is fakeredis:// for local/demo usage.

Installation

Prerequisites

• python 3.10+
• systemg (sysg CLI available on PATH)
• redis (server reachable by --redis-url)
• an LLM CLI: claude or codex

PyPI

pip install porki

From Source

git clone https://github.com/ra0x3/porki.git
cd porki
pip install -e .

Development Only (uv)

uv commands are for development workflows (not required for normal runtime use):

uv sync

Test

From repository checkout:

uv run pytest

Without uv:

python -m pip install pytest
python -m pytest

CLI Reference

usage: porki [-h] --role {agent,orchestrator} --instructions INSTRUCTIONS
             [--redis-url REDIS_URL] [--log-level LOG_LEVEL]
             [--agent-name AGENT_NAME] [--agent-role AGENT_ROLE]
             [--goal-id GOAL_ID] [--heartbeat HEARTBEAT]
             [--loop-interval LOOP_INTERVAL] [--lease-ttl LEASE_TTL]
             [--poll-interval POLL_INTERVAL]
             [--heartbeat-interval HEARTBEAT_INTERVAL]
             [--instruction-interval INSTRUCTION_INTERVAL]
             [--claude-cli CLAUDE_CLI] [--claude-extra-arg CLAUDE_EXTRA_ARG]
             [--claude-use-sysg] [--llm-provider {claude,codex}]
             [--llm-cli LLM_CLI] [--llm-extra-arg LLM_EXTRA_ARG]
             [--llm-use-sysg]

Porki agent/orchestrator entrypoint

options:
  -h, --help            show this help message and exit
  --role {agent,orchestrator}
                        Process role
  --instructions INSTRUCTIONS
                        Primary instructions file
  --redis-url REDIS_URL
                        Redis connection URL
  --log-level LOG_LEVEL
                        Python logging level
  --agent-name AGENT_NAME
                        Agent identifier when running in agent mode
  --agent-role AGENT_ROLE
                        Agent role identifier when running in agent mode
  --goal-id GOAL_ID     Goal identifier for the active DAG
  --heartbeat HEARTBEAT
                        Heartbeat file path for agent role
  --loop-interval LOOP_INTERVAL
                        Agent loop interval in seconds
  --lease-ttl LEASE_TTL
                        Lease TTL in seconds
  --poll-interval POLL_INTERVAL
                        Orchestrator poll interval in seconds
  --heartbeat-interval HEARTBEAT_INTERVAL
                        Agent heartbeat file read interval in seconds
  --instruction-interval INSTRUCTION_INTERVAL
                        Agent instructions reload interval in seconds
  --claude-cli CLAUDE_CLI
                        Path to the Claude CLI executable
  --claude-extra-arg CLAUDE_EXTRA_ARG
                        Additional arguments for the Claude CLI
  --claude-use-sysg     Invoke Claude through `sysg spawn --ttl` to capture
                        stdout/stderr
  --llm-provider {claude,codex}
                        LLM provider used for orchestration and agents
  --llm-cli LLM_CLI     Path to provider CLI executable
  --llm-extra-arg LLM_EXTRA_ARG
                        Additional arguments for the selected LLM CLI
  --llm-use-sysg        Invoke LLM CLI through `sysg spawn` for output capture