Working with Peer

Peer is an open-source local work delegation system. Each project has a Bot that understands your goal, coordinates work Agents and checks returned results. You keep the boundaries and the decisions that need you.

For the 0.1 Desktop preview, begin with a project Bot. Tasks and plans are how execution is organized behind that conversation. You do not need to choose Agent, Plan or Goal mode before your first project request.

The 0.0 stable release uses the classic interface. This guide labels preview features and retains the classic and CLI reference below.

Choose a version

The project Bot interface is in the 0.1 preview. Download the version you intend to use, read its release notes, and keep a backup of your complete data directory before upgrading.

Checked on 2026-10-29 against GitHub Releases and npm dist-tags. The GitHub release page lists actual platform assets; it is the download source.

Open download options

For the preview CLI, install the rc channel. Without @rc, npm installs the stable 0.0 release. The beta tag is an older beta channel, not the current RC.

npm install -g @peer-agent/cli@rc
peer --version
peer

Upgrade Desktop, CLI/TUI and Gateway according to the same release instructions. Older versions may not understand newer coordination data. Rollback follows the release-specific backup procedure; do not overwrite newer data with an old executable.

Your first project Bot

1. Install the 0.1 preview and open Peer. Add a model service in Settings, then choose a model that supports the capabilities your work needs.
2. Create a project Bot by binding a folder or creating a managed project. Give it a recognizable name and avatar.
3. Start with a goal and boundary: “Investigate this request latency. Explain the cause before changing the public API.”
4. Read the Bot’s understanding of the work. When execution is needed, it arranges scoped work with success criteria under your project permissions.
5. Keep using the main conversation for additions and decisions. Open the task details, report or workspace when you want the supporting material.

A useful first request

Read this project and explain its structure. Propose a plan for the README update; wait for my decision before broadening the scope.

The work panel groups tasks, child Agent progress, attention and saved materials while preserving the conversation and draft. The independent fourth pane holds web pages, files, diffs and read-only child conversations separately from Bot settings. Quote a saved reply to follow up on its source. Reading, authorizing a write and accepting a result remain distinct actions.

Smart input suggestions use one switch and a dedicated model in General settings. Requests require a selected model; adjacent disclosure explains use of the current conversation and unsent draft. Accepting a suggestion only edits the draft and does not send it.

The website screenshot uses fictional project data in the actual 0.1 Desktop renderer. It shows the interaction surface, not evidence that a model completed the example work.

Follow the work

The project Bot remains your point of contact while work is delegated. Independent work may run in parallel; a new message can add context, correct direction or stop scoped work.

Work questions and human decisions

Ordinary work questions should return to the main Bot for coordination. Missing authorization, material business choices and genuine requests for your input stay with you. A Bot cannot approve a permission card for you.

Read the kind of interruption

A stopped reply, a paused task, a failed attempt and an unknown tool outcome are different facts. Keep the original goal and inspect what happened before continuing. Resuming work must not blindly repeat unknown operations.

Interactive results are an opt-in preview. Open the saved result from its original reply or task to inspect the fixed version, filter rows or try inputs. To continue with those conditions, explicitly add them to your draft and send it. In the CLI, peer result reads the fixed summary.

Use Stop generating to stop the current reply. Continue trying resumes the same work from its saved progress when it is safe to proceed. Use the task controls to pause or cancel the whole work.

Open full conversation directly from the task list or the visible task summary. The separate Task details button starts collapsed and reveals verification, evidence and secondary controls. Task references beneath replies open the original task and label the recorded state At reply; open the task to check its current state.

When startup recovery needs attention, a recovery entry appears. Since RC29 it shows only while something still needs handling, and it can end all earlier executions after confirmation. Follow the visible recovery choices and preserve existing reports and worktrees.

RC29 strengthens durable supervision, context continuity and withdrawal settlement after old interrupted attempts.

Withdrawing a delegation ends follow-up responsibility after host settlement. It preserves history and may retain an unknown historical outcome; it does not prove that an external effect was rolled back.

Results and evidence

The main Bot should explain the result in terms of the goal: what changed, which checks ran and what remains unverified. Open the report, diff and evidence when you need detail.

Execution result

A tool or work Agent returned something. This alone does not close the whole delegation.

Verification

Checks are evaluated against the relevant success criteria and available evidence. Unknown and failed checks remain visible.

Acceptance and integration

Acceptance follows the configured policy and real verification facts. Git integration or an external action retains its own applicable authorization.

A summary helps carry context into another turn. It is not a replacement for a Tool Result, Evidence or a source reference.

Permissions and control

The local runtime owns capability execution and permission decisions. A task receives no broader authority than its project grant; model text does not create a grant.

Local execution does not mean every model runs locally. Review the selected provider and context/attachment permissions to understand which content can be sent to a model service.

Permission choices, stopping the current reply, pausing work, cancelling a task and withdrawing a delegation have different scopes. Read the operation label and the host receipt; closing a panel is not a stop request.

Advanced reference for the shared runtime, CLI and classic workflows. UI entry points and available operations depend on the release you installed.

Connect a model

Peer Agent is provider-flexible. Model config is local state. Keys should live in machine-side storage via the credential path, not in random project files.

Desktop

1. Open Settings → Models / Providers.
2. Add a provider (cloud API or local endpoint).
3. Store the key through the app credential flow when prompted.
4. Pick a default model + reasoning effort for new threads.
5. Send a trivial prompt to validate connectivity before real work.

CLI

In TUI, use /model to choose model and reasoning effort, and /language if you need Chinese/English reply policy changes. Provider credentials still resolve through the same local Runtime home.

Qoder private channel

The Qoder private channel is not an API-key service. It reuses the login state of a local Qoder CLI (qodercli) to reach Qoder's private inference endpoint. No key input is required — the signed-in CLI on this machine is the credential source.

Prerequisites

1. Install the Qoder CLI (qodercli) on this machine. Peer reads the CLI's local login files and uses the CLI's embedded auth module to sign requests; without the CLI this channel cannot work at all.
2. Sign in with qodercli first, and keep the session valid. Credentials live under ~/.qoder/.auth/; if you never signed in or the session expired, sign in again with the CLI.

Optional: set QODER_ACCESS_TOKEN / QODER_PERSONAL_ACCESS_TOKEN / QODER_PAT in the environment to supply the token instead of the local login files — but installing and signing into qodercli is still required for request signing.

If connecting fails, check the two prerequisites in order: CLI not installed → install qodercli; not signed in or session expired → sign in again in a terminal; empty model list → sign in once so the CLI caches the model catalog locally.

Advanced reference for the shared runtime, CLI and classic workflows. UI entry points and available operations depend on the release you installed.

CLI · peer

peer is a first-class TUI entry, not a secondary demo. It launches the vendor binary installed by @peer-agent/cli (or a Release archive) and talks to the same local Runtime as Desktop.

Start / verify

peer --version
peer

If version works but credentials fail after moving files, check that peer-credential-helper is still beside peer.

Shell commands

peer update
peer update --check
peer sessions
peer models
peer doctor
peer completions bash
peer export <id>

peer update installs the newest release on the channel already installed. --check only reports it. peer sessions delete also removes that session's goal plans and asks first unless --yes is passed. peer export writes a reading copy, not Evidence.

Status bar (what to read)

The TUI status row is meant to stay as governable as the GUI chips: mode, access/permission policy, model, reasoning effort, and context usage. Treat it as the terminal equivalent of Desktop composer metadata.

Slash commands (real registry)

Type / in the composer. Commands below come from the TUI command registry (labels/descriptions simplified for docs).

Shared Runtime home

~/.peer-agent
  settings / providers
  conversations
  credentials (via peer-credential-helper)
  runtime artifacts / evidence refs

Desktop and CLI are different shells over one local state root. That is intentional product design, not a coincidence.

Advanced reference for the shared runtime, CLI and classic workflows. UI entry points and available operations depend on the release you installed.

Local Runtime

Peer Agent’s product spine is the local Capability Runtime. Desktop and CLI are shells. Capability truth is local.

Design philosophy

Local owns capability.
Interface owns expression.
Contract owns boundaries.
Evidence owns governance.

Capability chain (enforced)

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

• Provider — discovers/implements a capability family (files, shell, MCP…).
• Manifest — declares what the capability is, not ad-hoc free text.
• Runtime Projection — exposes model-visible tools without bypassing governance.
• Tool Call — model intent becomes a structured call.
• PermissionGrant — local authorization decision before execution.
• Evidence — factual result trail (artifacts/logs/metadata), not a chat paraphrase.

Runtime stack (product view)

Electron Desktop shell  +  peer TUI shell
            \                 /
             local Runtime home (~/.peer-agent)
                      |
        Capability Runtime + Agent Runtime
                      |
     files / shell / web / MCP / plugins / skills

Advanced reference for the shared runtime, CLI and classic workflows. UI entry points and available operations depend on the release you installed.

Capabilities overview

Capabilities are declared through providers/manifests, projected to the model as tools, then executed only after PermissionGrant. There is no blessed “secret side door” for shell vs MCP vs plugins vs skills.

Extending Peer Agent

Prefer a new Provider + Manifest path over hardcoding capabilityId branches into central hosts. That keeps Runtime Projection, permissions, and Evidence consistent as the surface grows.

Advanced reference for the shared runtime, CLI and classic workflows. UI entry points and available operations depend on the release you installed.

MCP servers

MCP (Model Context Protocol) servers are loaded from Peer Agent’s local registry. Installation is not the same as enablement: a disabled server can exist without being projected as model-visible tools.

Operational flow

1. Install/register an MCP server into the local registry.
2. Enable it (Desktop settings/registry UI or CLI /mcp).
3. Re-sync / inspect tools — confirm projected tool list.
4. Run a task that needs those tools; approve PermissionGrant if prompted.
5. Verify Evidence shows the MCP tool call and result refs.

CLI

Use /mcp to manage servers and inspect tool status without leaving the TUI.

Advanced reference for the shared runtime, CLI and classic workflows. UI entry points and available operations depend on the release you installed.

Skills

A Skill is a reusable instruction package for the agent — not a remote tool server. Peer Agent loads Skills from local packages (SKILL.md), can browse Tencent SkillHub and the Qoder marketplace from Desktop, manages enable/disable state, and injects selected skill context into the conversation under the same Runtime governance chain.

What a Skill is

• Package — a folder or archive containing SKILL.md (required) plus optional assets/.
• Frontmatter — name/description, optional whenToUse, allowed-tools, license metadata.
• Body — the procedure / playbook the model should follow when the skill is active.
• Local store — installed skills live under the app user-data skill root; enable/disable is persisted in local settings.

Skill vs Plugin vs MCP

Package shape

my-skill/
  SKILL.md          # required (YAML frontmatter + markdown body)
  assets/           # optional attachments
  ...

Install sources include zip and tgz archives that contain SKILL.md at the archive root (or one top-level folder that contains it), plus Desktop browse/install from Tencent SkillHub and the Qoder marketplace. Empty descriptions are treated as invalid noise and dropped.

Lifecycle on device

1. Discover / install — load from local skill roots, install from zip/tgz, or browse Tencent SkillHub / Qoder marketplace on Desktop into the user skill store.
2. List — each skill exposes id, name, description, whenToUse, version, enabled state.
3. Enable / disable — disabled skills remain installed but stay out of the active set.
4. Borrow / link — optional source roots can expose available skills that can be linked into the local store.
5. Use in a thread — insert or invoke skill context; model follows the playbook while tools still require grants.
6. Refresh — re-scan roots / store after install or external edits.

CLI: /skill

In the TUI slash palette, /skill opens Skills management: browse installed skills, enable/disable, refresh, insert, or invoke. Desktop has the corresponding Skills UI over the same store concepts.

When to use Skills

• Repeatable workflows you want the agent to follow consistently (release checklist, review rubric, incident playbook).
• Team conventions that should travel as packages, not as one-off prompt paste.
• Domain procedures that should stay local and auditable, with optional tool allow-lists.

If you need a live external API tool surface, prefer MCP. If you need a new local execution provider family, prefer Plugin/Provider — not a Skill body pretending to be a tool host.

Advanced reference for the shared runtime, CLI and classic workflows. UI entry points and available operations depend on the release you installed.

Plugins

A Plugin is a local capability package — the packaging and distribution unit for local providers, adapters, optional local MCP configs, permission declarations, and install metadata. Plugins do not own cognition and are not the permission source of truth.

What a Plugin is

• Capability package — one or more capability manifests shipped together.
• Local adapters — how those capabilities actually run on the device (native bridge, local process, etc.).
• Optional local MCP config — a Plugin may bundle or register local MCP servers, but MCP remains a transport, not the product object.
• Install metadata — publisher, version, signature/trust metadata, settings/diagnostics contributions.

Plugin vs Skill vs MCP

Still the same chain

Plugin package
  → Capability Manifest(s)
    → Runtime Projection
      → Tool Call
        → PermissionGrant
          → Local execution
            → Evidence

Any Plugin, Skill, or MCP server must enter this path. There is no blessed side door for “plugin tools” that skip projection or grants.

What a Plugin can contain

Local registration layers

Local registration is designed as three layers that must not be mixed into one folder:

1. Built-in — first-party capabilities shipped with the client (for example Local Shell is a core provider, not a random plugin).
2. User-installed — formal packages recorded under Electron userData plugin registry (e.g. plugins/registry.json).
3. Workspace / dev — development-time manifests (compatibility path under workspace capabilities/*.json) for debugging, not third-party distribution.

Lifecycle (product view)

1. Install / register — package lands in the user plugin registry or a declared source root.
2. Discover manifests — Runtime loads capability manifests from the package.
3. Project — only projected capabilities become model-visible tools for the current workspace/session.
4. Authorize — user PermissionGrant (or valid prior grant scope) before execution.
5. Execute locally — adapters / local MCP run on the device.
6. Evidence — structured results return as Evidence / ClientToolResult trail.

Local Shell is not “just a plugin”

Local Shell / Bash is a first-class high-risk built-in Capability Provider. It is modeled as core local power with command safety classification and Evidence, not as an ordinary third-party plugin toggle.

When to use a Plugin

• You need a new local capability family (adapters/providers) packaged for install and update.
• You want to ship local MCP + manifests + settings metadata as one distributable unit.
• You need clear publisher/install metadata and a governed enable path on the device.

If you only need a reusable playbook, use a Skill. If you only need an external tool transport, use MCP. If you need cloud-only business APIs, that belongs to cloud MCP / cloud projection — not a local Plugin pretending to be remote control.

Questions

Do I have to manage every task myself?

In the 0.1 Desktop preview, use the project Bot as your main point of contact. Task details remain available when you need to inspect execution or evidence.

Are tasks and GoalPlan gone?

They remain the execution and governance foundation. The product entry point is a project relationship; bounded tasks, plans, criteria and evidence organize the work behind it.

Does local-first mean no data leaves the computer?

No. Tools, permissions and evidence are controlled locally, while a chosen cloud model receives the content admitted to that request. Review provider and context permissions.

Where are Agent, Plan and Goal modes?

They remain relevant in the CLI and classic interface. Goal mode carries structured goals, criteria and resumable state. The project Bot preview organizes Desktop work through the project conversation.

Can the Bot simply say the work is done?

A reply cannot stand in for execution or evidence. Look at the host’s verification, acceptance and integration facts, including any explicit limits.

Why distinguish preview and development changes?

A source change, a passing CI run and a published installer are different stages. Consult the actual release notes for what your installed build contains.