Skip to content

docs: update README for Show HN launch #730

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 1 commit into from
Mar 8, 2026
Merged

docs: update README for Show HN launch #730

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
96 changes: 57 additions & 39 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,49 +1,50 @@
# Perstack

A harness for micro-agents.
# Perstack: A Harness for Micro-Agents.

<p align="center">
<a href="https://github.com/perstack-ai/perstack/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License"></a>
<a href="https://www.npmjs.com/package/perstack"><img src="https://img.shields.io/npm/dm/perstack" alt="npm downloads"></a>
<a href="https://www.npmjs.com/package/perstack"><img src="https://img.shields.io/npm/v/perstack" alt="npm version"></a>
<a href="https://hub.docker.com/r/perstack/perstack"><img src="https://img.shields.io/docker/v/perstack/perstack?label=docker" alt="Docker image version"></a>
<a href="https://hub.docker.com/r/perstack/perstack"><img src="https://img.shields.io/docker/v/perstack/perstack?label=docker&sort=semver" alt="Docker image version"></a>
</p>

<p align="center">
<a href="https://perstack.ai"><strong>Documentation</strong></a> ·
<a href="https://perstack.ai/docs/"><strong>Docs</strong></a> ·
<a href="https://perstack.ai/docs/getting-started/"><strong>Getting Started</strong></a> ·
<a href="https://discord.gg/2xZzrxC9"><strong>Discord</strong></a>
<a href="https://perstack.ai/"><strong>Website</strong></a> ·
<a href="https://discord.gg/2xZzrxC9"><strong>Discord</strong></a> ·
<a href="https://x.com/FL4T_LiN3"><strong>@FL4T_LiN3</strong></a>
</p>

If you're looking for a way to build practical agentic apps like Claude Code or OpenClaw, you'll need a harness to manage the complexity.
If you want to build practical agentic apps like Claude Code or OpenClaw, a harness helps manage the complexity.

Perstack is a harness for agentic apps. It aims to:

- **Do big things with small models**: If a smaller model can make the same thing, there's no reason to use a bigger model.
- **Quality is a system property, not a model property**: Building agentic software that people use doesn't require AI science degree, just knowledge to solve their problems.
- **Keep it simple and reliable**: The biggest mistake is cramming AI into an overly complex harness and ending up with an uncontrollable agent.
- **Do big things with small models**: If a smaller model can do the job, there's no reason to use a bigger one.
- **Quality is a system property, not a model property**: Building agentic software people actually use doesn't require an AI science degree—just a solid understanding of the problems you're solving.
- **Keep it simple and reliable**: The biggest mistake is cramming AI into an overly complex harness and ending up with an inoperable agent.

## Getting Started

Perstack is designed so that defining experts, running them, and integrating them into applications remain separate concerns.
Perstack keeps expert definition, orchestration, and application integration as separate concerns.

`create-expert` scaffolds experts, the harness handles orchestration, and deployment stays simple because Perstack runs on standard container and serverless infrastructure.

### Defining your first expert

To get started, you can use the `create-expert` Expert that helps you to focus on the core and build your first agentic AI:
To get started, use the built-in `create-expert` expert to scaffold your first agentic app:

```bash
# Ask `create-expert` to form a team named `ai-gaming`
# Use `create-expert` to scaffold a micro-agent team named `ai-gaming`
docker run --pull always --rm -it \
-e FIREWORKS_API_KEY \
-v ./ai-gaming:/workspace \
perstack/perstack start create-expert \
--provider fireworks \
"Form a team named ai-gaming to build a Bun-based CLI cutting-edge indie game playable on Bash."
--model accounts/fireworks/models/kimi-k2p5 \
"Form a team named ai-gaming to build a Bun-based CLI indie game playable on Bash for AI."
```

`create-expert` is a built-in Expert. It 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.
`create-expert` is a built-in expert. It generates a `perstack.toml` that defines a team of micro-agents, runs them, evaluates the results, and iterates until the setup works. Each agent has a single responsibility and its own context window. Complex tasks are broken down and delegated to specialists.

```toml
[experts."ai-gaming"]
Expand All @@ -69,30 +70,46 @@ instruction = "Play-test the game, find bugs, and verify fixes."
To let your agents work on an actual task, you can use the `perstack start` command to run them interactively:

```bash
# Let `ai-gaming` team build a Wizardry-like dungeon crawler
# Let `ai-gaming` build a Wizardry-like dungeon crawler
docker run --pull always --rm -it \
-e FIREWORKS_API_KEY \
-v ./ai-gaming:/workspace \
perstack/perstack start ai-gaming \
--provider fireworks \
"Make a Wizardry-like dungeon crawler. Make it replayable, so players can dive in, die, and find a way to beat it."
--model accounts/fireworks/models/kimi-k2p5 \
"Create a Wizardry-like dungeon crawler in a fixed 10-floor labyrinth with complex layouts, traps, fixed room encounters, and random battles. Include special-effect gear drops, leveling, and a skill tree for one playable character. Balance difficulty around build optimization. Death in the dungeon causes loss of one random equipped item."
```

Here is an example of a game built with these commands: [demo-dungeon-crawler](https://github.com/perstack-ai/demo-dungeon-crawler). It was built entirely using Kimi K2.5 on Fireworks for under $0.10 in total API cost. You can play it directly:
Here is an example of a game built with these commands: [demo-dungeon-crawler](https://github.com/FL4TLiN3/demo-dungeon-crawler). It was built entirely with Kimi K2.5 on Fireworks. You can play it directly:

```bash
npx perstack-demo-dungeon-crawler start
```

<details>
<summary>Generation stats for demo-dungeon-crawler</summary>

| | |
|---|---|
| **Date** | March 8, 2026 |
| **Duration** | 32 min 44 sec |
| **Steps** | 199 |
| **Generated Code** | 13,587 lines across 25 files |
| **Tokens (Input)** | 11.4M (Cache: 10.7M) |
| **Tokens (Output)** | 257.3K |
| **Cost** | $2.27 (via Fireworks) |

</details>

### Integrating with your app

Perstack separates the agent harness from the application layer. Your app stays a normal web or terminal app, with no LLM dependencies in the client.

```
┌─────────────────┐ ┌──────────────────┐
│ Your app │ events │ perstack run │
│ (React, TUI…) │◄─────────── │ (@perstack/ │
│ │ SSE / WS / │ runtime) │
│ (React, TUI…) │ ◄─────────── │ (@perstack/ │
│ │ SSE / WS / │ runtime) │
│ @perstack/ │ any stream │ │
│ react │ │ │
└─────────────────┘ └──────────────────┘
Expand All @@ -110,7 +127,7 @@ RUN perstack install
ENTRYPOINT ["perstack", "run", "my-expert"]
```

The image is ubuntu-based, multi-arch (`linux/amd64`, `linux/arm64`) and weighs ~74MB. The runtime can also be imported directly as a TypeScript library ([`@perstack/runtime`](https://www.npmjs.com/package/@perstack/runtime)) for serverless environments. See the [deployment guide](https://perstack.ai/docs/operating-experts/deployment/) for details.
The image is Ubuntu-based, multi-arch (`linux/amd64`, `linux/arm64`), and is ~74 MB. `perstack install` pre-resolves MCP servers and prewarms tool definitions for faster, reproducible startup. The runtime can also be imported directly as a TypeScript library ([`@perstack/runtime`](https://www.npmjs.com/package/@perstack/runtime)) for serverless environments. See the [deployment guide](https://perstack.ai/docs/operating-experts/deployment/) for details.


### Why micro-agents?
Expand Down Expand Up @@ -166,27 +183,29 @@ perstack start my-expert "query" --env-path .env.production

## What's inside?

Perstack organizes the complexity of an agent harness into five layers with clear separation of concerns:
An agent harness needs a broad set of capabilities—almost like an operating system.

```
┌──────────────────────────────────────────────────────────────────┐
│ Interface │
│ CLI · TUI · Event streaming · Programmatic API │
├──────────────────────────────────────────────────────────────────┤
│ Runtime │
│ Agentic loop · Event-sourcing · Checkpointing · Tool use │
├──────────────────────────────────────────────────────────────────┤
│ Context │
│ System prompts · Prompt caching · Agentic RAG · Extended thinking│
├──────────────────────────────────────────────────────────────────┤
│ Definition │
┌──────────────────────────────────────────────────────────────────-┐
│ Interface │
│ CLI · Event streaming · Programmatic API │
├──────────────────────────────────────────────────────────────────-┤
│ Runtime │
│ Agentic loop · Event-sourcing · Checkpointing · Tool use │
├──────────────────────────────────────────────────────────────────-┤
│ Context │
│ System prompts · Prompt caching · AgenticRAG · Extended thinking │
├──────────────────────────────────────────────────────────────────-┤
│ Definition │
│ Multi-agent topology · MCP skills · Provider abstraction │
├──────────────────────────────────────────────────────────────────┤
│ Infrastructure │
├──────────────────────────────────────────────────────────────────-┤
│ Infrastructure │
│ Sandbox isolation · Workspace boundary · Secret management │
└──────────────────────────────────────────────────────────────────┘
└──────────────────────────────────────────────────────────────────-┘
```

Most of the features below are not new ideas. Perstack takes the usual harness building blocks — tool use, delegation, checkpointing, prompt caching, etc. — makes them easy to operate, puts them on top of standards you already know (MCP, TOML, Docker, SSE), and ships them as one runtime. Where cost or operational burden demands it, Perstack introduces its own take — micro-agents being the first example.

<details>
<summary>Full feature matrix</summary>

Expand Down Expand Up @@ -245,13 +264,12 @@ Perstack organizes the complexity of an agent harness into five layers with clea

## Status

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/).
Pre-1.0. The runtime is production-tested, but the API surface may change. [Pin your versions](https://perstack.ai/docs/references/cli/).

## Community

- [Discord](https://discord.gg/2xZzrxC9)
- [GitHub Issues](https://github.com/perstack-ai/perstack/issues)
- [@FL4T_LiN3 on X](https://x.com/FL4T_LiN3)
- [Author on X(@FL4T_LiN3)](https://x.com/FL4T_LiN3)

## Contributing

Expand Down