English | 简体中文

Psychevo

Psychevo is a local coding agent for work in an existing codebase. Set up a
provider, then run tasks from the terminal, local Workbench, or a supported ACP
editor. Configuration, permission policy, and session history stay local and
inspectable.

What you can do

• Work where you prefer: run a one-shot task with pevo run, use the full-screen
  terminal UI, open local Workbench, launch Desktop from a source checkout, or
  connect a supported ACP editor.
• Choose a provider, model, and agent: configure an OpenAI-compatible provider,
  then use local agents or managed Codex, OpenCode, and Hermes ACP backends when
  they are available.
• Extend and delegate: combine filesystem-backed skills, plugins, hooks,
  MCP-backed tools, local agents, and subagent flows.
• Connect approved WeChat, Telegram, Feishu, and Lark conversations through the
  managed Gateway when chat is the right interface.

Psychevo focuses on dependable local execution today. It does not claim
autonomous evaluation loops, workflow mining, or long-term memory.

Install From Source

Psychevo currently installs from source. Install Git, Rust/Cargo, a native
compiler, Node.js, and pnpm, then run the checkout-local installer:

git clone https://github.com/wowfun/psychevo.git
cd psychevo
sh scripts/install.sh --check
sh scripts/install.sh

The installer builds the local pevo binary and Workbench Web UI assets. See
the Installation Guide for prerequisites, diagnostics,
Windows Git Bash notes, network troubleshooting, and development commands.

For a CLI-only install, use the underlying Cargo command:

cargo install --locked --path crates/psychevo-cli --force

For development without installing:

cargo run -p psychevo-cli -- --help
pnpm --filter @psychevo/workbench dev

Quick Start

Set up Psychevo once for your provider and model:

pevo setup

The wizard initializes Psychevo home, configures a provider and model, stores
or references an API key, checks Web UI assets, and finishes with a doctor
summary. Confirm the local setup without contacting a provider:

pevo doctor

Run your first task from the project you want to work on:

pevo run "summarize this repository"

Open an interactive workspace when you need one:

pevo tui
pevo web

For editor integration, configure an ACP client to start pevo acp; see the
ACP Configuration Guide.

Select a provider/model for one invocation:

pevo run -m deepseek/deepseek-chat "inspect the CLI entrypoints"

Documentation

• Rust and Python SDK Guide
• Installation Guide
• ACP Configuration Guide
• Channels Guide
• TUI Troubleshooting
• Contributing Guide

Rust and Python SDKs

The psychevo Rust crate runs the Framework in process. One Application
owns Thread and Turn state, accepted work, controls, interactions, and ordered
shutdown:

use psychevo::{Application, StartThreadRequest, TurnRequest};

let application = Application::builder()
    .home("/tmp/psychevo-sdk")
    .build()
    .await?;
let client = application.client();
let thread = client
    .start_thread(StartThreadRequest::new("."))
    .await?;
let turn = thread
    .start_turn(TurnRequest::new("Inspect this repository"))
    .await?;
let result = turn.wait().await?;
application.shutdown().await?;

The async Python SDK starts its exact-version bundled App Server over stdio by
default:

from pathlib import Path

import psychevo


async with psychevo.Client() as client:
    thread = await client.start_thread(cwd=Path.cwd())
    turn = await thread.start_turn("Inspect this repository")
    result = await turn.wait()
    print(result.final_answer)

The Python client also accepts an explicit App Server executable or an
authenticated WebSocket URL. It does not search PATH, download binaries, or
discover a daemon. See the SDK Guide for lifecycle, events,
controls, callbacks, transport configuration, and package layout.

More ways to work

Commands

Run pevo <command> --help for flags and subcommands.

Development

Read AGENTS.md before changing the project. Psychevo is spec-first:
before behavior, public docs, tests, or workflow changes, read and update the
best-fit specs/<topic>/spec.md.

Rust workspace broad gate:

cargo xtask ci run --profile rust-broad

Use narrower validation when it covers the changed behavior. Live-provider,
API-key, and live-service checks are opt-in only.

Repo-local live validation is xtask-owned:

cargo xtask init dev-env
cargo xtask live run
cargo xtask live run --env isolated
cargo xtask live run --suite provider

Useful local commands:

cargo run -p psychevo-cli -- --help
cargo test -p psychevo-cli smoke_cli
pnpm --filter @psychevo/workbench build
pnpm --filter @psychevo/workbench dev

Workspace for contributors

License

Psychevo is licensed under the MIT License.