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.
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.
[!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:
- Open Settings and connect a model provider or an installed local runtime.
- Choose the workspace Pragma is allowed to use.
- Talk with Pragma to create your own Expert, ExpertTeam, or Flow.
- 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:
- Try opening Pragma normally.
- If macOS blocks it, open System Settings → Privacy & Security and choose Open Anyway.
- 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
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
- Use the right model × harness for each step. A model inside a coding agent, browser agent, or domain tool is a different execution capability. Pragma routes work without locking the whole workflow to one vendor.
- Carry context across the whole Mission. Requirements, decisions, artifacts, review findings, and task state move forward by value or controlled reference. Each Expert receives the context it needs without replaying every transcript.
- Compose without losing governance. Experts, Teams, and Flows can become steps or governed tools. Nested work remains inside one Execution with a shared audit trail for handoffs, output, approvals, usage, cancellation, and recovery.
- Keep humans in control. Flows can pause for clarification, approval, or review, and Desktop owns local workspace access and permission decisions.
- Move methods between systems. A
.pragma bundle can carry portable DSL and selected project assets. Desktop can import it, while another Host can load it through @pragma/interpreter and run the compiled object through @pragma/core.
Flow = Expert + ExpertTeam + SubFlow + Human checkpoints
Expert tools = Expert + ExpertTeam + Flow
Example: an AI-native delivery mission
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 是一个跨运行框架的平台，把 AI 原生的工作方法变成可复用的代理团队，将模型、工具、上下文、记忆和工作流组合在一起，让你可以在 Desktop、CLI 中运行同一个团队，或通过 SDK 嵌入。