Skip to content

README.md

Latest commit

 

History

History
130 lines (92 loc) · 5.95 KB

README.md

File metadata and controls

130 lines (92 loc) · 5.95 KB

Peri Code

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

License Rust Platform Models Stars

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.

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**<br/>Terminal (ratatui)"]
    IDE["**Zed / JetBrains**<br/>IDE (ACP client)"]
    STDIO["**Stdio**<br/>Headless / CI / Cloud"]

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

    ACP["**peri-acp** — ACP Server<br/>session · executor · prompt · commands"]

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

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

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 (x86_64 / Apple Silicon), Linux (x86_64 / 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

Acknowledgments

License

Apache 2.0