Skip to content

docs: rewrite README to align with HN launch post #598

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
FL4TLiN3 merged 5 commits into from
Feb 22, 2026
Merged

docs: rewrite README to align with HN launch post #598

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ee3347b
docs: rewrite README to align with HN launch post
FL4TLiN3 Feb 22, 2026
0d3a2a7
docs: lead README with problem statement
FL4TLiN3 Feb 22, 2026
b445c29
docs: rewrite README opening with problem-first structure
FL4TLiN3 Feb 22, 2026
9716c8e
docs: condense README opening to half the length
FL4TLiN3 Feb 22, 2026
35ab784
docs: add one-liner explaining create-expert and perstack relationship
FL4TLiN3 Feb 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 77 additions & 68 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Perstack: An Agentic AI Runtime
# Perstack

<p align="center">
<a href="https://www.npmjs.com/package/perstack"><img src="https://img.shields.io/npm/v/perstack" alt="npm version"></a>
Expand All @@ -12,102 +12,111 @@
<a href="https://discord.gg/perstack"><strong>Discord</strong></a>
</p>

**No coding. No setup. Just ask.**
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.

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 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?
## Tools

You've tried building AI agents. You know how it goes.
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.

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.
Custom MCP servers can be added per agent in `perstack.toml`.

Perstack separates what the agent does from how your app works.
## Deployment

| 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. |
```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

Expand Down