Peri

Peri Code

A Rust-built coding agent — fast, lean, Claude Code compatible, any LLM.

[](https://opensource.org/licenses/Apache-2.0) [](https://www.rust-lang.org/) [](#install) [](#why-peri) [](https://github.com/konghayao/peri)

One 13 MB binary, ~50 MB of RAM, 98% cache hits. Bring your own API key — DeepSeek, GLM, Qwen, or Anthropic, switch on the fly. Your existing Claude Code config works today, not eventually: skills, hooks, MCP, plugins, sub-agents. Zero migration, zero lock-in.

99% of the codebase was written by AI (DeepSeek & GLM-5.2), shipped by humans who decided what to build. The agent files its own bugs, fixes them, and writes the lessons back into the repo. More on that [below](#built-by-ai-published-by-human).

---

Why Peri

• 🦀 Rust, not Node.js
• 13 MB binary, ~50 MB RAM. Won't sneak up to 1 GB while you're not looking
• ⚡ 95–99% cache hit rate
• Frozen system prompt + boundary marker = near-zero wasted tokens
• 🌐 Any LLM
• Anthropic, OpenAI, DeepSeek, GLM, Qwen. Swap mid-session, no restart
• 🪟 Cross-platform
• macOS, Linux, Windows — one binary. ConPTY-aware event handling, unified overlay textarea, cross-platform spawn
• 🔌 Drop-in Claude Code compatible
• Existing Claude Code config just works. Skills, hooks, MCP, plugins — zero migration
• 🔍 Tool Search
• The LLM only sees what it needs. ~14 core tools, rest discovered on demand — lean prompts, fat cache hits
• 📝 Streaming Markdown
• Code blocks, tables, diffs — fully rendered as the agent types, not after
• 🤖 Sub-agents & background agents
• 7 built-in specialists (coder, explorer, code-reviewer, web-researcher…). Fork work to the background and keep going
• 🗜️ Auto Compact
• Hours-long sessions stay fast and cheap, automatically
• 📦 agm
• agm install any skill or agent. One lockfile, any tool
• 🌐 Web Terminal (peri web)
• Browser-based remote shell, one command. xterm.js + multi-pane split, auto open browser
• 🔧 Built-in LSP & observability
• Language-aware intelligence out of the box. Langfuse traces, token usage, cache monitor

---

Architecture

Peri is not just a TUI. It's a layered platform where the agent core is decoupled from the frontend via the Agent Client Protocol. The same core powers three entry points:

graph TD
    TUI["**peri-tui**Terminal (ratatui)"]
    IDE["**Zed / JetBrains**IDE (ACP client)"]
    STDIO["**Stdio**Headless / CI / Cloud"]

    TUI -->|MpscTransport| ACP
    IDE -->|ACP Stdio| ACP
    STDIO -->|ACP Stdio| ACP

    ACP["**peri-acp** — ACP Serversession · executor · prompt · commands"]

    ACP --> AGENT["**peri-agent**ReAct loop · LLM adapter · tools · SQLite storage"]
    ACP --> MW["**peri-middlewares**18 middlewares: FS · HITL · SubAgent · Skills · MCP · Hooks · Compact"]
    ACP --> LSP["**peri-lsp**LSP client"]

    AGENT -.->|telemetry| LF["**langfuse-client**"]
    MW -.->|renders with| WIDGETS["**peri-widgets**Markdown · code blocks · tables"]

One core, three frontends. Terminal users get peri-tui. IDE users connect via ACP (Zed today, more to come). Headless / CI / cloud scenarios use the Stdio transport. Change the agent logic once — every frontend benefits.

---

Install

Binaries available for macOS (x8664 / Apple Silicon), Linux (x8664 / aarch64 / riscv64), and Windows (x86_64).

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/konghayao/peri/main/scripts/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/konghayao/peri/main/scripts/install.ps1 | iex

# start peri
peri

# self-update
peri update

First launch guides you through model and API key configuration — no config file editing required.

---

Built by AI, Published by Human

Peri's code is 99% AI-generated, primarily by DeepSeek and GLM-5.2. The development workflow is a closed loop the agent drives itself:

| When you... | The loop kicks off | |---|---| | Find a bug or tech debt | issue-create → systematic-debugging → writing-plans → subagent-driven-development → issue-archive → update CLAUDE.md | | Want a new feature | grill-me → writing-plans → subagent-driven-development | | Codebase getting messy | slop-cleaner → improve-codebase-architecture → writing-plans → subagent-driven-development |

Each fix that reveals a non-obvious constraint gets written back into CLAUDE.md as a TRAP — a hard rule the agent follows on every subsequent iteration. The dozens of TRAPs in the repo weren't authored by humans; they were extracted by the agent at the scene of each bug. That's how quality compounds without human code review.

→ Read the full story: [Nobody Coding](docs/blogs/ai-coding-paradigm/nobody-coding.md)

---

---

Acknowledgments

• Claude Code Best — community support and feedback
• Superpowers & Matt Pocock's Skills — the skill suites that drive Peri's AI engineering workflow
• ACP — open protocol for agent-IDE communication
• rmcp — Rust MCP client library
• Ratatui & Tokio
• Langfuse — LLM observability
• Zed — first ACP-compatible IDE

License

Apache 2.0

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: KonghaYao
• Source: KonghaYao/peri
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.