From ee3347bcd14829d45d08fce6fbf1261217b8dd8d Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Sun, 22 Feb 2026 08:05:16 +0000 Subject: [PATCH 1/5] docs: rewrite README to align with HN launch post MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove marketing copy and competitive comparison tables. Add concrete demo link, deployment examples, and runtime details. Align tone with the Show HN post — facts and code over claims. Co-Authored-By: Claude Opus 4.6 --- README.md | 143 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 75 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 0fa3c7fc..9f34cc92 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Perstack: An Agentic AI Runtime +# Perstack

npm version @@ -12,102 +12,109 @@ Discord

-**No coding. No setup. Just ask.** +Agentic AI runtime for building and running multi-agent systems. Define agents in TOML, execute them on any LLM provider. ```bash -npx create-expert "form an indie-game-dev team that builds high-quality 2D games for the browser" -npx perstack start indie-game-dev "Cyberpunk pixel-art beat 'em up for the browser" +npx create-expert "Form a team named ai-gaming to build a Bun-based CLI indie game playable on Bash for AI." +npx perstack start ai-gaming --model "haiku-4-5" "Make a Wizardry-like dungeon crawler." ``` -`create-expert` turns ideas into runnable agent definitions. The runtime inside `perstack` executes them. No magic — just a properly designed agentic system. +A game built with these commands: [demo-dungeon-crawler](https://github.com/perstack-ai/demo-dungeon-crawler). Play it via `npx perstack-demo-dungeon-crawler start`. Built entirely on Claude 4.5 Haiku. -## Under the Hood +## How it works -1. **`create-expert`** generates a `perstack.toml` — agent behavior defined in plain English. It iteratively tests and refines the definition for you until it actually works. -2. **`perstack start`** executes the agents defined in `perstack.toml` and streams their activity in real time. -3. **Both run on `@perstack/runtime`** — an event-sourced, checkpointed runtime for long-running agents. Resume, replay, or diff executions across model changes whenever you want. -4. **`@perstack/base`** gives agents real-world tools (files, shell, etc.) via MCP. -5. **Complex tasks?** Agents delegate to specialist experts in parallel. +`create-expert` generates a `perstack.toml` that defines a team of micro-agents. Each agent has a single responsibility and its own context window. Complex tasks are broken down and delegated to specialists. +```toml +[experts."ai-gaming"] +description = "Game development team lead" +instruction = "Coordinate the team to build a CLI dungeon crawler." +delegates = ["@ai-gaming/level-designer", "@ai-gaming/programmer", "@ai-gaming/tester"] -### What `create-expert` actually generates +[experts."@ai-gaming/level-designer"] +description = "Designs dungeon layouts and game mechanics" +instruction = "Design engaging dungeon levels, enemy encounters, and progression systems." -The indie-game-dev example above produces something like this: +[experts."@ai-gaming/programmer"] +description = "Implements the game in TypeScript" +instruction = "Write the game code using Bun, targeting terminal-based gameplay." -```toml -[experts."indie-game-dev"] -description = "Indie game development team lead" -instruction = "Coordinate the team to build a high-quality 2D browser game." -delegates = ["@indie-game-dev/game-designer", "@indie-game-dev/programmer", "@indie-game-dev/artist", "@indie-game-dev/qa-tester"] +[experts."@ai-gaming/tester"] +description = "Tests the game and reports bugs" +instruction = "Play-test the game, find bugs, and verify fixes." +``` -[experts."@indie-game-dev/game-designer"] -description = "Designs game mechanics and level structure" -instruction = "Design engaging gameplay systems and level progression." +`perstack start` executes the agents and streams activity in real time. `perstack run` does the same headless with JSON output, for integration into your own applications. -[experts."@indie-game-dev/programmer"] -description = "Implements the game in TypeScript" -instruction = "Write clean, performant game code using HTML5 Canvas." +## Runtime -[experts."@indie-game-dev/artist"] -description = "Creates pixel art assets" -instruction = "Produce consistent pixel art sprites, tilesets, and UI elements." +The runtime (`@perstack/runtime`) is event-sourced. Every execution produces a hierarchy of Jobs, Runs, and Checkpoints. -[experts."@indie-game-dev/qa-tester"] -description = "Tests and finds bugs" -instruction = "Play-test the game, report bugs, and verify fixes." -``` +- **Resume** from any checkpoint if an execution is interrupted. +- **Replay** executions across different models to compare behavior. +- **Inspect** execution history with `perstack log`. -Plain English. No SDK. No glue code. This file *is* the agent. +Each agent runs in isolation with its own context window and tools. Agents communicate through shared workspace files, not shared conversation history. -## Go Deeper +## Providers -| Topic | Link | -| :--- | :--- | -| Build your first agent | [Rapid Prototyping Guide](https://perstack.ai/guides/rapid-prototyping/) | -| Break complex agents into specialists | [Taming Prompt Sprawl](https://perstack.ai/guides/taming-prompt-sprawl/) | -| Give agents real-world tools via MCP | [Extending with Tools](https://perstack.ai/guides/extending-with-tools/) | -| Deploy to Docker, AWS, GCP, Cloudflare | [Deployment](https://perstack.ai/docs/operating-experts/deployment/) | -| Architecture and core concepts | [Understanding Perstack](https://perstack.ai/docs/understanding-perstack/concept/) | -| Expert definitions in depth | [Making Experts](https://perstack.ai/docs/making-experts/) | -| CLI and runtime API reference | [References](https://perstack.ai/docs/references/cli/) | -| Examples: bug-finder, github-issue-bot, gmail-assistant | [examples/](./examples/) | +Anthropic, OpenAI, Azure OpenAI, Google, Vertex AI, DeepSeek, Ollama, Bedrock. -## Why Perstack? +The architecture is designed around running purpose-specific agents on efficient models. A well-defined agent on Haiku can do what a monolithic agent on Opus struggles with, at a fraction of the cost. -You've tried building AI agents. You know how it goes. +## Tools -The prompts live in your application code. You can't test the agent without deploying the whole app. When you want to tweak behavior, it's a code change, a PR, a deploy. Domain experts who actually understand the task can't touch the prompts without a developer. And when something breaks, you're reading raw LLM logs trying to figure out which step went wrong. +Agents access the outside world through MCP (Model Context Protocol). `@perstack/base` provides built-in tools: file read/write/edit, shell execution, image and PDF reading. -Perstack separates what the agent does from how your app works. +Custom MCP servers can be added per agent in `perstack.toml`. -| You want to... | How Perstack handles it | -| :--- | :--- | -| **Test an agent idea in 30 seconds** | `npx create-expert "..."` — running agent, no app needed. | -| **Change agent behavior** | Ask `create-expert` again. It updates, tests, and refines on your request. | -| **Let non-developers tune the agent** | Edit the definition in `perstack.toml`. The definition is plain English. | -| **Debug a failed execution** | Describe the failure to `create-expert`. It can diagnose and fix Expert definitions. | -| **Run agents safely in production** | Each agent gets its own context window. | -| **Avoid LLM vendor lock-in** | Major providers are supported. Perstack is open-source. | +## Deployment + +```dockerfile +FROM node:22-slim +WORKDIR /app +COPY perstack.toml perstack.lock . +RUN npm install -g perstack && perstack install +ENTRYPOINT ["perstack", "run", "--config", "/app/perstack.toml", "ai-gaming"] +``` -**Coming from other tools?** +The runtime can also be imported directly as a TypeScript library, so it works in Cloudflare Workers, Vercel, or any Node.js environment: -| If you use... | Perstack is for you if... | +```typescript +import { run } from "@perstack/runtime" + +const checkpoint = await run({ + setting: { + model: "claude-sonnet-4-5", + providerConfig: { providerName: "anthropic", apiKey: env.ANTHROPIC_API_KEY }, + expertKey: "ai-gaming", + input: { text: query }, + }, +}) +``` + +## Documentation + +| Topic | Link | | :--- | :--- | -| **LangGraph / PydanticAI** | You don't want to build your own tool integrations, agent loop, and error-feedback plumbing just to get a real agentic system running. | -| **CrewAI / AutoGen / Google ADK** | You want runtime-level isolation per agent, full event sourcing, and no shared process. | -| **OpenAI Agents SDK** | You want true multi-provider — not Response API with a compatibility layer on top. | -| **Mastra / Vercel AI SDK** | You've hit the wall between prototype and production — job management, agent isolation, long-running lifecycles. | -| **Raw LLM SDK calls** | You're tired of building the agent loop, checkpointing, and orchestration from scratch. | +| Getting started | [Getting Started](https://perstack.ai/docs/getting-started/) | +| Architecture and core concepts | [Understanding Perstack](https://perstack.ai/docs/understanding-perstack/concept/) | +| Expert definitions | [Making Experts](https://perstack.ai/docs/making-experts/) | +| Rapid prototyping | [Rapid Prototyping Guide](https://perstack.ai/guides/rapid-prototyping/) | +| Breaking agents into specialists | [Taming Prompt Sprawl](https://perstack.ai/guides/taming-prompt-sprawl/) | +| Adding tools via MCP | [Extending with Tools](https://perstack.ai/guides/extending-with-tools/) | +| Deployment | [Deployment](https://perstack.ai/docs/operating-experts/deployment/) | +| CLI and API reference | [References](https://perstack.ai/docs/references/cli/) | -Perstack is not a framework, an orchestrator, or a UI layer. It is an **agentic AI runtime** — the execution engine that sits between your application and the LLM providers. Define agents above it. Build interfaces on top of it. +## Status -Perstack is pre-1.0. The runtime is stable and used in production, but the API surface may evolve. [Pin your versions](https://perstack.ai/docs/references/cli/). +Pre-1.0. The runtime is stable and used in production, but the API surface may change. [Pin your versions](https://perstack.ai/docs/references/cli/). -## Join the Community +## Community -- **[Discord](https://discord.gg/perstack)** — Ask questions, share what you're building, get help. -- **[GitHub Issues](https://github.com/perstack-ai/perstack/issues)** — Bug reports, feature requests, ideas. -- **[@FL4T_LiN3 on X](https://x.com/FL4T_LiN3)** — Building Perstack in public. Follow for updates. +- [Discord](https://discord.gg/perstack) +- [GitHub Issues](https://github.com/perstack-ai/perstack/issues) +- [@FL4T_LiN3 on X](https://x.com/FL4T_LiN3) ## Contributing From 0d3a2a7014dfb5f3b995366a9371d589e877b8ca Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Sun, 22 Feb 2026 08:12:12 +0000 Subject: [PATCH 2/5] docs: lead README with problem statement Co-Authored-By: Claude Opus 4.6 --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9f34cc92..001573ad 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,9 @@ Discord

-Agentic AI runtime for building and running multi-agent systems. Define agents in TOML, execute them on any LLM provider. +Most agentic AI frameworks require writing large amounts of glue code — tool integrations, agent loops, error handling, state management — before the agent can do anything useful. And when it finally runs, it runs on a frontier model that costs too much to scale commercially. + +Perstack takes a different approach: define agents in a TOML file, orchestrate them as purpose-specific micro-agents on efficient models, and run them on an event-sourced runtime with built-in isolation. ```bash npx create-expert "Form a team named ai-gaming to build a Bun-based CLI indie game playable on Bash for AI." From b445c298b00feeac4ac1ff7ffab252f30a37da79 Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Sun, 22 Feb 2026 08:17:33 +0000 Subject: [PATCH 3/5] docs: rewrite README opening with problem-first structure Frame the two walls (boilerplate trap, cost gap) as the problem, then position micro-agent orchestration on value-tier models as the approach. Remove redundant claims from Providers section. Co-Authored-By: Claude Opus 4.6 --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 001573ad..e66755f5 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,13 @@ Discord

-Most agentic AI frameworks require writing large amounts of glue code — tool integrations, agent loops, error handling, state management — before the agent can do anything useful. And when it finally runs, it runs on a frontier model that costs too much to scale commercially. +Building agentic software that actually works in production is hard. There are two common approaches, and both hit a wall. -Perstack takes a different approach: define agents in a TOML file, orchestrate them as purpose-specific micro-agents on efficient models, and run them on an event-sourced runtime with built-in isolation. +One is to write the agent from scratch. The amount of boilerplate — tool integrations, agent loops, state management, error recovery — is large enough that the actual prompts, the part that defines what the agent does, become a small fraction of the codebase. Most of the effort goes into plumbing, not intelligence. + +The other is to throw a frontier model at a monolithic prompt. Opus-class models are powerful enough to compensate for a vague, sprawling agent definition. But the cost makes commercial deployment impractical. + +Perstack is built around a third option: break the work into purpose-specific micro-agents, each with a focused prompt, and run them on value-tier models. A well-scoped agent on Haiku doesn't need Opus-level reasoning — the task is narrow enough that a 2024-era frontier model's capability is more than sufficient. And because each agent has a single job, the prompts are short and easy to write. ```bash npx create-expert "Form a team named ai-gaming to build a Bun-based CLI indie game playable on Bash for AI." @@ -62,8 +66,6 @@ Each agent runs in isolation with its own context window and tools. Agents commu Anthropic, OpenAI, Azure OpenAI, Google, Vertex AI, DeepSeek, Ollama, Bedrock. -The architecture is designed around running purpose-specific agents on efficient models. A well-defined agent on Haiku can do what a monolithic agent on Opus struggles with, at a fraction of the cost. - ## Tools Agents access the outside world through MCP (Model Context Protocol). `@perstack/base` provides built-in tools: file read/write/edit, shell execution, image and PDF reading. From 9716c8e7bf1f716b6cddfe9765e773ae91b4d5d9 Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Sun, 22 Feb 2026 08:19:54 +0000 Subject: [PATCH 4/5] docs: condense README opening to half the length Co-Authored-By: Claude Opus 4.6 --- README.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e66755f5..f92c64e1 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,9 @@ Discord

-Building agentic software that actually works in production is hard. There are two common approaches, and both hit a wall. +Agentic software in production hits two walls. Build from scratch, and most of the code is plumbing — not prompts. Throw a frontier model at a monolithic agent, and it works but doesn't scale commercially. -One is to write the agent from scratch. The amount of boilerplate — tool integrations, agent loops, state management, error recovery — is large enough that the actual prompts, the part that defines what the agent does, become a small fraction of the codebase. Most of the effort goes into plumbing, not intelligence. - -The other is to throw a frontier model at a monolithic prompt. Opus-class models are powerful enough to compensate for a vague, sprawling agent definition. But the cost makes commercial deployment impractical. - -Perstack is built around a third option: break the work into purpose-specific micro-agents, each with a focused prompt, and run them on value-tier models. A well-scoped agent on Haiku doesn't need Opus-level reasoning — the task is narrow enough that a 2024-era frontier model's capability is more than sufficient. And because each agent has a single job, the prompts are short and easy to write. +Perstack takes a third approach: purpose-specific micro-agents on value-tier models. Narrow tasks don't need Opus-level reasoning. Haiku is enough. And single-purpose prompts are easy to write. ```bash npx create-expert "Form a team named ai-gaming to build a Bun-based CLI indie game playable on Bash for AI." From 35ab784c705950a085bbde2aab831de9f0de2043 Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Sun, 22 Feb 2026 08:22:24 +0000 Subject: [PATCH 5/5] docs: add one-liner explaining create-expert and perstack relationship Co-Authored-By: Claude Opus 4.6 --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index f92c64e1..18e81db9 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ Agentic software in production hits two walls. Build from scratch, and most of t Perstack takes a third approach: purpose-specific micro-agents on value-tier models. Narrow tasks don't need Opus-level reasoning. Haiku is enough. And single-purpose prompts are easy to write. +`create-expert` generates agent definitions in a `perstack.toml` file. `perstack` executes them on an event-sourced runtime. + ```bash npx create-expert "Form a team named ai-gaming to build a Bun-based CLI indie game playable on Bash for AI." npx perstack start ai-gaming --model "haiku-4-5" "Make a Wizardry-like dungeon crawler."