pragma README

The project's README from github.com/pqpo/pragma. As one markdown file: README.md.

launher

Pragma

English | 简体中文

Build Your Agent Team Once. Use It Everywhere.

Build portable AI agent teams across models and harnesses — combine the right models, tools, context, and workflows for each task. Run them directly through Pragma Desktop or CLI; bring them into Codex, Claude Code, and other tools without changing your workflow; or integrate them into your own AI system with the SDK.

Latest preview release Project status: preview Desktop platform: macOS License: AGPL-3.0

Download · Quick start · Document · Examples

Pragma is a cross-harness platform for turning AI-native working methods into runnable, reusable agent teams. A team can combine Experts, ExpertTeams, Flows, tools, Skills, shared context, memory, permissions, and human checkpoints—not just a prompt.

Unlike a single chat product or Coding Agent, Pragma treats the Agent Team and its working method as the portable unit. Define it as YAML DSL and build it in Desktop, run it from the terminal through the CLI, or embed the same team in your own application with the SDK.

During a Mission, work can move between specialists without losing decisions, artifacts, or accumulated experience. The same team can coordinate different models and harnesses for different steps while keeping context, permissions, handoffs, and execution under one governance model.

Pragma Desktop running a multi-expert mission

Pragma Desktop running a multi-expert mission

Pragma Desktop running a multi-expert mission

[!IMPORTANT] Pragma is currently a preview. The latest Desktop release provides builds for macOS Apple Silicon and Intel. Verify that a package comes from the official release before installing it.

Quick start

Run Pragma Desktop

Download the package for your Mac from GitHub Releases, install it, and then:

  1. Open Settings and connect a model provider or an installed local runtime.
  2. Choose the workspace Pragma is allowed to use.
  3. Talk with Pragma to create your own Expert, ExpertTeam, or Flow.
  4. Start a task with the result and use it as much as you like. As Missions accumulate, cross-harness memory turns repeated experience into stable knowledge and reusable Skills.

To open a Desktop release, use this order:

  1. Try opening Pragma normally.
  2. If macOS blocks it, open System Settings → Privacy & Security and choose Open Anyway.
  3. Only if it still cannot open, and you have verified that the package came from the official release, clear the app's quarantine attribute:
sudo xattr -r -d com.apple.quarantine /Applications/Pragma.app

You do not need to change the global Allow apps downloaded from setting.

The Desktop distribution guide explains the release contents, checksums, and installation process.

Build Desktop from source

Requirements: Node.js 22 or later and pnpm 10.12.1.

git clone https://github.com/pqpo/pragma.git
cd pragma
pnpm install --frozen-lockfile
pnpm --filter @pragma/desktop dev

Development builds use ~/.pragma-development/ by default so unreleased storage migrations cannot modify data owned by the installed Desktop app. Set PRAGMA_HOME explicitly only when a task intentionally needs another isolated data root.

Try the SDK and runtime adapters

The repository includes runnable examples rather than abbreviated API fragments:

# ContextStore operations; no model credentials required
pnpm --filter @pragma/examples example:context

# Use an installed and authenticated local agent CLI
pnpm --filter @pragma/examples example:runtime-codex
pnpm --filter @pragma/examples example:runtime-claude-code

See the examples guide for Expert sessions, delegation, ExpertTeams, Flows, human review gates, MCP, Skills, plugins, memory, recovery, and portable bundles.

What Pragma makes reusable

Pragma's three compounding assets: workflows, private knowledge, and private evaluation sets

AI working methods

Compose Experts, ExpertTeams, Flows, subflows, tools, and human checkpoints. Each step can bind the model, agent harness, permissions, and context that fit the task. The resulting method can be versioned, evaluated, exported, and shared.

Private knowledge

Pragma treats context as a Host-owned ContextStore instead of trapping it inside one chat product. Events from different tasks, harnesses, and models enter a shared Memory Pipeline and become evidence-backed episodic and semantic memory. As that dynamic memory accumulates, background work can automatically start a policy-controlled promotion workflow that turns it into stable knowledge or reusable Skills; authoritative changes are activated only after the required review.

The ContextStore contract is extensible. This repository currently includes in-memory, JSON, filesystem, Mission Board, and Memory-backed implementations; other databases or retrieval systems can be added through Host adapters.

Private evaluation sets

Reusable workflows need regression signals. Evaluations capture the tasks and expectations that matter to you, so changes to a prompt, Flow, model, runtime, or context source can be checked at the system level instead of judged from a single demo.

These assets compound: workflows produce evidence, memory turns evidence into knowledge, and evaluations reveal whether the next revision is actually better.

Why Pragma

Flow         = Expert + ExpertTeam + SubFlow + Human checkpoints
Expert tools = Expert + ExpertTeam + Flow

Example: an AI-native delivery mission

An example collaborative delivery workflow

In this example configuration, UI design, requirements, architecture, implementation, and independent review use different specialists. Accepted decisions and artifacts flow between stages, and useful facts, experience, and Skills remain available to the next Mission.

The model and runtime names in the diagram are illustrative. Routing is a Host binding: the reusable method is not coupled to those exact providers.

Choose how to build and run your Agent Team

Pragma meets you at three levels: a full-featured Desktop workspace, direct CLI invocation, or SDK integration into your own system.

Desktop — the most intuitive entry point

Use Pragma Desktop as the most intuitive and configurable way to build and run teams. Configure model providers, local runtimes, permissions, context, memory, tools, and evaluations; create Experts and Flows in Studio; run Missions; inspect results; and import or export .pragma bundles.

CLI — call teams directly from the terminal

Install @pqpo/pragma to discover Experts, run or resume Missions, inspect results and events, answer HumanTask interactions, and manage Mission queues from the terminal. JSON and JSONL output provide stable envelopes for scripts and other Agent tools, while the CLI and Desktop share the same Local Host application semantics.

SDK — integrate teams into your own system

Save an Agent Team as versioned YAML DSL, load and compile it with @pragma/interpreter, and invoke the compiled team directly from your own application through @pragma/core. This path lets you embed Agent Team execution into a product or AI system while keeping the team definition portable and reviewable. Start with the portable bundle example and the DSL architecture guide; runnable integrations live in examples/src.

Available capabilities

Area Capabilities
Desktop macOS Apple Silicon and Intel packages
CLI macOS and Windows npm package with human-readable, JSON, and JSONL output
Runtime adapters Claude Code, Codex, PI, Qoder CLI, and Antigravity
Composition Expert, ExpertTeam, Flow, SubFlow, HumanTask, and governed delegation
Context In-memory, JSON, filesystem, Mission Board, and Memory-backed stores
Memory Evidence pipeline, episodic and semantic modules, Knowledge, and Skill refinement
Evaluation Versioned Evaluation resources and Flow Run Dry
Portability .pragma bundle import, export, validation, binding, compilation, and Git bundle sources
Recovery Durable Mission commands, Execution events, Runtime Session ownership, and schema migrations

For detailed implementation boundaries, see the current architecture overview.

Documentation

Contributing and support

Read the Contributing Guide before opening a pull request. Use GitHub Issues for reproducible bugs and feature proposals, and follow the Security Policy for vulnerability reports.

License

Pragma is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). If you modify Pragma and offer that modified version for remote network interaction, AGPL-3.0 requires you to offer those users access to the corresponding source code. Pragma names, logos, and official identity are governed separately by the Trademark Policy.

pragma (pqpo/pragma)

Searching Database…

251 ·GitHub
Pragma
What is this?Pragma is a cross-harness platform for turning AI-native working methods into reusable Agent Teams that combine models, tools, context, memory, and workflows, so you can run the same team in Desktop, the CLI, or embed it via SDK.
Is this a desktop app, a CLI, or a library?It is all three: a macOS Desktop app for building and running teams visually, a CLI (@pqpo/pragma) for invoking them from the terminal, and an SDK (@pragma/interpreter plus @pragma/core) for embedding a compiled team in your own application.
How do I get started with Pragma?Download the Desktop package for your Mac from GitHub Releases and install it, open Settings to connect a model provider or local runtime, then talk with Pragma to create your own Expert, ExpertTeam, or Flow. Alternatively, install the CLI via npm or build Desktop from source.
Is Pragma stable enough to rely on right now?No, the project explicitly calls itself a preview, and the Desktop release currently only ships macOS Apple Silicon and Intel builds, so you should verify packages come from the official release before installing.
Does Pragma Desktop run on Windows or Linux too?Desktop packages currently ship for macOS only (Apple Silicon and Intel); the CLI npm package additionally works on Windows. Linux support is not mentioned.
What's the catch with the AGPL license?Pragma uses AGPL-3.0-only, which means if you modify it and offer that version over a network, you must make the corresponding source code available to those users.
What is a Mission in Pragma?A Mission is a run of an Agent Team where work moves between specialists without losing decisions, artifacts, or task state, and the resulting evidence feeds Memory and Evaluations.
Which AI harnesses can Pragma route work to?Current runtime adapters cover Claude Code, Codex, PI, Qoder CLI, and Antigravity, so a single team can combine different models and harnesses across steps without locking into one vendor.
What's inside a .pragma bundle?A .pragma bundle packages the portable YAML DSL definition of an Agent Team plus selected project assets, so Desktop can import it or another Host can load and run it through @pragma/interpreter and @pragma/core.
How does Pragma turn past tasks into reusable Skills?Events from tasks flow into a shared Memory Pipeline that becomes evidence-backed episodic and semantic memory; a policy-controlled promotion workflow can turn that memory into stable knowledge or reusable Skills after review.
What are similar projects?ruflo, Agentlas-OS, codify, deer-flow, awesome-opencode, operator-memory, oh-my-openagent, MiMo-Code
Which topics is it in?agent-team, agentic-workflow, yaml, context-engineering, agent-framework, agent-memory, memory, workflow, orchestration, agent-orchestration, skills, sdk
Creator
pqpo
Size
44.2 MB
Stars
251
Updated
CommitOct 17
Age
3mo
Commits · 90 Days