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

porki run --help

porki instructions --help

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

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

porki run \
  --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

One-shot prompt mode:

porki run --prompt "Draft a concise architecture summary for this repo."

Enable colored logging output (similar to cargo):

porki run --role orchestrator --instructions INSTRUCTIONS.md --color

The --color flag enables ANSI color codes for log levels:

• INFO: Green
• DEBUG: Light Blue (Cyan)
• WARNING: Yellow
• ERROR: Red

The --log-style flag controls log verbosity:

• concise (default): human-first logs with only meaningful context keys.
• event: full structured key/value event suffix on each line.

Create a template instruction file:

porki instructions create --name "Core infra dev" --path ./instructions

Generated templates now include canonical JSON schema examples for goals, DAG tasks, task state, finished tasks, and LLM response payloads. Each generated file also includes explicit version metadata (porki_instruction_template_version and porki_schema_version) so upgrades are trackable.

Example output path from the command above:

./instructions/CORE_INFRA_DEV.md

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] [--version] {run,instructions} ...

Porki agent/orchestrator entrypoint (version X.Y.Z)

positional arguments:
  {run,instructions}
    run               Run orchestrator/agent loops or submit a one-shot prompt
                      to the configured LLM
    instructions      Instruction file utilities

options:
  -h, --help          show this help message and exit
  --version           Show version and exit

usage: porki run [-h] [--role {agent,orchestrator}]
                 [--instructions INSTRUCTIONS] [-p [PROMPT]]
                 [--redis-url REDIS_URL] [--log-level LOG_LEVEL]
                 [--log-style {concise,event}] [--color]
                 [--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]

usage: porki instructions [-h] [--log-level LOG_LEVEL]
                          [--log-style {concise,event}] [--color] {create} ...

usage: porki instructions create [-h] -n NAME -p PATH [--force]
                                 [--log-level LOG_LEVEL]