A fully open-source, local-first Task Flow Agent — work moves through task handoff, continuity, and follow-up questions; authorized, planned, and proven on your machine.

Fully open source (MIT) · Local-first · Permission-gated · Evidence-backed · Task flow by default

English · 简体中文

Quick Start · Why · Philosophy · Task Flow · Features · Architecture · Vision · Roadmap

Many coding agents already run tools on your machine. That alone is no longer a differentiator.

Peer Agent is fully open source (MIT) — not an "open shell around a closed core": Desktop, TUI, CLI, the runtime, the protocol, and every capability manifest ship under the same LICENSE. Audit every line of permission code, fork your own branch, or embed the runtime in your own host.

Peer Agent is about what happens after local execution: goals are accepted with boundaries, ambiguity is clarified instead of guessed, work is planned by complexity, and completion is proven with Evidence — under one permissioned capability chain across Desktop, TUI, and CLI.

Three first-class shells share one unified core runtime:

Peer Agent is built around a simple split of responsibility:

Product principles we try not to violate:

• Elegance first — Prefer one clear concept over two overlapping ones; refuse “good enough” seams that will rot.
• Task over chat — Multi-step work is accepted as a goal with boundaries and success criteria, not freelanced mid-conversation.
• Ask when blocked — Material ambiguity and high-risk trade-offs interrupt; silent guessing does not.
• Prove completion — Done means tool results and Evidence, not assertive prose.
• One capability chain — Shell, files, browser, MCP, plugins, and skills all pass through the same permission + Evidence path.

These ideas shape both the product surface (Agent / Plan / Goal) and the engineering baseline in the companion knowledge base.

Peer Agent treats multi-step work as a task, not a free-form chat turn. Tasks are first-class citizens — each with its own objective, boundaries, success criteria, and lifecycle.

From acceptance to closure, a task walks an explicit chain:

Accept (objective + boundaries + success criteria) → Clarify → Plan (L0–L3 depth) → Execute → Verify → Acceptance & close

• Planning depth scales with complexity: L0 answers directly; L1 runs a short plan before acting; L2 drives a self-directed GoalPlan with trackable subtasks; L3 high-risk / irreversible work goes through an explicit Plan review before any side effect.
• Agent is the default; Plan is the brake when you want review first.
• Dispatch–acceptance loop: tasks can be dispatched (e.g. cloud-scheduled execution) — but only after you approve or reject the dispatch. The dispatched run walks an explicit dispatching → acked → running → result_received state chain; results pass a quality self-check, then wait for your acceptance before they count as delivered — not "the model says it's done".
• Subtasks and success criteria close only with real tool results and Evidence — not "done" prose.

Real work gets interrupted: contexts fill up, processes restart, you step away for lunch. Peer Agent treats these as first-class scenarios:

• Persistent Goal state: the plan graph, subtask status, success criteria, and Evidence are all persisted — tasks survive across sessions.
• Pause / resume / waiting_user: a task can park on "waiting for your reply" and continue from the breakpoint when you return, without losing context.
• Compact summaries + context checksums: long-task context is compacted into a continuity summary to keep going — but a summary is continuity context, not proof. Closing a task always requires real tool results.
• Read-only Explorer workers may investigate in parallel, while the lead task flow retains scope, budget, and completion ownership.

When material information is missing, Peer Agent's rule is ask, don't guess:

• Structured follow-up: the request_user_input tool asks with clickable options — you pick instead of typing a paragraph. Your reply is recorded as a persistent state transition.
• Ask at the right moment: only critical ambiguity, risky trade-offs, or missing permissions interrupt you; routine execution stays quiet.
• Answers belong to the task: follow-up replies attach to the task itself — on the next resume or the next dispatch, the answer is still there.

Task flow and the capability chain each govern their own half: task flow decides what work is accepted and when it's finished; local execution always goes through one chain:

Capability Provider → Manifest → Runtime Projection → Tool Call → PermissionGrant → Evidence

The capability chain decides how local power is authorized and proven.

It doesn't matter where work enters — config, permissions, and Evidence are always the same:

“Shared across surfaces” means the same user and data home on one machine. Peer does not claim cloud synchronization of secrets across devices.

• 🔌 MCP as a first-class citizen — external MCP servers plug straight in and go through the same permission + Evidence pipeline as built-ins; no side door
• 🏪 Plugin & skill marketplace — Marketplace-style install, enable/disable, and updates; skills trigger workflows on demand
• 🧱 Declarative capability manifests — every capability is described by a manifest (permissions, entry points, parameters) and projected uniformly into model-visible tools
• 🔌 Open Runtime SDK — @peer-agent/protocol / runtime-core / runtime-sdk let any Node host embed the same governed capability pipeline; host-neutral, not tied to Electron
• 📎 Governed context admission — attachments, files, and web content enter context through explicit admission paths, not free-form prompt injection

• ✅ Dispatch needs your consent — dispatching a task (e.g. cloud-scheduled execution) requires your approve/reject first; nothing ships out silently
• 🔗 Explicit state chain — dispatching → acked → running → result_received, every step observable
• 🧪 Quality self-check + user acceptance — results pass a quality self-check, then wait in a pending-acceptance state; it counts as delivered only after you accept
• 🌿 Isolated runs — repository jobs can run in a dedicated Git worktree and return commit / diff artifact refs and a receipt, never silently mutating your active checkout
• 🗣️ Roundtable — multi-participant sessions under a governance mode; interject into the current roundtable at any time

• 🔐 One secure credential vault — macOS Keychain, Windows Credential Manager, or Linux Secret Service protects a random 32-byte master key; Provider secrets are encrypted locally with AES-256-GCM
• 🧑‍🏫 Main + fallback vision — Choose any main model for reasoning and optionally pair it with a vision-capable fallback; image recognition stays a supporting role and the main model continues the task

• 📁 Files · 💻 Shell · 🔍 Search · 🧰 Local tooling — always via Runtime Projection + PermissionGrant + Evidence

1. Download a release from GitHub Releases

   Platform	First-class artifact	Notes
   macOS arm64	Peer-Agent-<ver>-arm64.dmg	Developer ID signed and notarized. In-app auto-update (latest-mac.yml + zip) starts from 0.0.18; 0.0.17 and earlier must install 0.0.18 manually once.
   Windows x64 / arm64	Peer-Agent-Setup-<ver>.exe
   Linux x64	Peer-Agent-<ver>-x64.AppImage (preferred) or .deb	Unsigned (stage-1). In-app auto-update is AppImage-only (latest-linux.yml). Ubuntu 22+/24+ AppImage users may need libfuse2. linux-arm64 Desktop is not a Release asset yet.

2. Install and open Peer Agent

3. Add a model provider / API key in settings

4. Start a conversation — or hand it a real goal and let Agent mode drive

On Linux Wayland, if the window fails to appear, try X11 or ELECTRON_OZONE_PLATFORM_HINT=auto.

npm install -g @peer-agent/cli
peer --version
peer
peer exec "summarize this repo"

The npm package downloads the platform peer binary from GitHub Releases on install. macOS arm64 (peer-darwin-arm64.tar.gz) and Linux x64 (peer-linux-x64.tar.gz) are first-class today; other platforms fail clearly in postinstall until their Release assets ship.

# Prerequisites: Node.js 20+, pnpm, Rust toolchain (for native pieces)

git clone https://github.com/ly-ccx/Peer-Agent.git
cd Peer-Agent
pnpm install

# Desktop (Electron)
pnpm --filter @peer-agent/desktop dev

# Linux Desktop unpacked dir (sandbox / smoke)
pnpm pack:linux

# Linux Desktop distributables (AppImage + .deb; needs libdbus-1-dev, fakeroot, dpkg)
pnpm dist:linux

# Terminal agent (TUI)
pnpm --filter @peer-agent/tui dev

Workspace packages live under apps/ (product shells) and packages/ (runtime, protocol, CLI publish package @peer-agent/cli).

The architecture starts from a single point: the agent runtime. Everything else is a layer peeled off it.

The bottom layer answers one question: when the model wants a local capability, on what authority does it run, and how is it proven?

Capability Provider → Manifest → Runtime Projection → Tool Call → PermissionGrant → Evidence

@peer-agent/runtime-core is the pure implementation of this core: capability registry, manifests, projection, authorization, and Evidence primitives, plus context compaction and accounting. It knows nothing of Electron, terminals, or any product shape — only contracts. @peer-agent/protocol defines the contracts themselves (chat, execution, goal, system-context, automation, compaction — 13 domains) as cross-layer types, so every layer speaks the same language.

No side doors. Bash, files, search, MCP, plugins, skills — every capability flows through the same chain. That is the non-negotiable part of this architecture.

The runtime executes capabilities, but the model first needs context. @peer-agent/system-context is the canonical assembler for System Context: prompt-source registration, layering, checksums, and snapshots. Project instructions, mode reminders, tool prompts, and compact summaries enter through explicit Context Sources — not scattered string concatenation. Tool output and file content are factual context and are never promoted into system instructions.

Above capability and context sits the machinery of tasks: @peer-agent/chat-kernel (reducer-driven conversation state machine) and @peer-agent/task-thread (task-thread event model) carry handoff, continuity, and follow-up; the goal contract defines GoalPlans, subtasks, and success criteria; @peer-agent/conversation-store persists it all so tasks survive across sessions.

@peer-agent/runtime-node lands the core in a Node environment: MCP server integration, the Automation scheduler, the chat runtime, and encrypted credentials (with @peer-agent/credential-helper and the system Secret Service). @peer-agent/runtime-sdk opens the same orchestration to any Node host for embedding.

Desktop (apps/desktop), TUI, and CLI (apps/tui + @peer-agent/cli) do expression and interaction only — they hold no execution truth. Host-neutrality is not a slogan, it is a dependency fact: the TUI depends on no UI packages, only on protocol + runtime-core + runtime-node + runtime-sdk + system-context; Desktop additionally uses chat-kernel / task-thread / ui / i18n. One machine, one ~/.peer-agent — different surfaces, one truth.

┌──────────────────────────────────────────────────────────┐
│  Desktop / TUI / CLI        (expression + interaction)  │
└───────────────────────────┬──────────────────────────────┘
                            │ protocol / IPC
┌───────────────────────────▼──────────────────────────────┐
│  Agent Runtime                                            │
│  ① runtime-core + protocol   capability chain · auth · Evidence │
│  ② system-context            Context Sources · assembly  │
│  ③ chat-kernel + task-thread task flow · goal · persistence │
│  ④ runtime-node              MCP · Automation · credentials │
│  ⑤ runtime-sdk               host embedding              │
└───────────────────────────┬──────────────────────────────┘
                            │ provider routing / model API
┌───────────────────────────▼──────────────────────────────┐
│  Cognition (your model stack)  Official · OAuth/subscription · Coding Plan · custom │
└──────────────────────────────────────────────────────────┘

peer_agent/
├── apps/            # Desktop, TUI/CLI product shells
├── packages/        # protocol · runtime-core/node/sdk · system-context
│                    # chat-kernel · task-thread · conversation-store
│                    # credential-helper · i18n · ui · npm-cli
├── capabilities/    # Capability manifests (local.shell.* / local.web.* / …)
├── crates/          # Rust native components
├── marketplace/     # Plugin / skill marketplace assets
├── skills/          # Bundled skills
├── docs/            # Site assets (logo, pages)
└── scripts/         # Build / release tooling

Peer Agent aims to be a cross-platform agent OS for real work — not another chat window that can shell out.

The long-term product spine:

Philosophy stays fixed while the surface grows: cognition is pluggable; authorization and Evidence stay local.

These are direction, not shipping claims. They are not available in the current release.

Issues, discussions, and PRs are welcome.

1. Fork and create a branch
2. Keep changes scoped; prefer protocol/runtime seams over one-off branches
3. Add or update tests when you touch contracts, permissions, or tool execution
4. Open a PR with a clear problem statement and verification notes

Please do not expand renderer direct fs / child_process access, bypass Runtime Projection, or replace Evidence with free-form assistant text.

MIT © 2026 梁音

_{Built for people who want AI that can act — with authorization, task flow, and Evidence.}