peen

module
v0.38.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: MIT

README

peen

Go Reference CI coverage version license imported by Docker Pulls

peen goes in vageen

Peen is a coding agent built as a server. One control server opens a session for each workspace directory and runs Peen's agent for that session in its own worker, either a process beside the controller or a separate Docker container. Clients send work and watch it live over WebSocket, and the agent keeps working when they disconnect. It can read code, edit files, run commands, use skills, launch child agents, and follow the AGENTS.md and rules sitting beside the project.

Every conversation, tool call, agent event, context snapshot, compaction, and provider exchange lands in SQLite. Model records keep the request and response, thinking, usage, retries, cost, model identity, and connection name, never the provider credential. Reconnect after a restart and the history is still there. A global WebSocket receives every session's live feed; a session-filtered socket receives only that session.

Root and nested agent conversations run through SQLite-backed go-workflows. After a controller or worker crash, Peen restores saved context and reuses completed activity results. Stop pauses unfinished work, and reconnecting leaves it paused. Ask an agent to inspect and explicitly continue the retained task; uncertain tool effects need inspection before retry. See recovery and continuation.

One host runs one control plane. It owns SQLite, the API, and the event feed, and the operator chooses whether workers run as child processes or containers. See Where it runs and Architecture.

Peen ships its own browser control surface at the controller's root URL. It is one client among many, so a terminal client, a bot, or your own application can watch the same live work and use the same stored records.

Contents

Install

You need Linux, a model provider API key, and, for the default setup, Docker that your user can run.

curl -fsSL https://raw.githubusercontent.com/psyb0t/peen/main/install.sh | bash

Read install.sh before piping it into a shell. It installs the peen command in ~/.local/bin, pins the newest release image, and writes your configuration to ~/.config/peen/.env.

By default Peen runs in a container and gives each workspace's agent its own container. Where it runs says what the agent can touch in each setup, and Deployment lists every installer flag, the peen commands, and the manual routes.

Run it

Add your model provider first. Peen refuses to start until the provider that serves your default model answers and every key the file names is set.

peen config edit

Keep the provider you use, delete the other entry together with its key variable, and set both models to one of its models. For an OpenAI-compatible AIGate setup, the important lines look like this:

PEEN_UPSTREAMS=[{"name":"aigate","type":"openai","baseUrl":"https://aigate.example/v1","apiKeyEnv":"AIGATE_TOKEN"}]
PEEN_DEFAULT_MODEL=aigate/your-model-id
PEEN_COMPACTION_MODEL=aigate/your-model-id
AIGATE_TOKEN=your-token-here
PEEN_API_TOKEN=

The file is a Docker --env-file, so leave the JSON unquoted. For a server outside your own machine, set PEEN_API_TOKEN to a real secret before starting it. peen doctor checks the result. Configuration lists every setting.

Then open a project:

cd ~/work/my-app
peen

peen starts Peen when it is not running, opens the session for the current directory, and prints its link, http://127.0.0.1:8080/?session=<id>, opening it in your browser when it can. Run it again in the same directory and you get the same session back, with its history. To run one turn from the shell instead:

peen --prompt "fix the tests"

Getting started walks through the first run, and the command line guide has every flag.

Security

The agent's file tools and runCommand have the full access of the account its worker runs as, with no path allowlist and no approval step. A Docker agent space is the isolation boundary. Tool output is stored and streamed verbatim, unredacted. A session with no client attached keeps running and spending provider budget until something stops it. Set PEEN_API_TOKEN and use wss:// outside local development. Read Security before you deploy Peen anywhere it can reach something you do not want touched.

GitHub action

Run a prompt as a workflow step on a Linux runner with Docker. Your workflow prepares the directory, including checkout when needed. Peen runs the prompt, streams its reply, and returns result and result-file outputs.

- uses: psyb0t/peen@main
  id: peen
  with:
    prompt: Explain this project and write a summary to SUMMARY.md.
    working-directory: .
    model: gateway/your-model-id
    upstreams: >-
      [{"name":"gateway","type":"openai","baseUrl":"https://gateway.example/v1","apiKeyEnv":"PROVIDER_KEY"}]
  env:
    PROVIDER_KEY: ${{ secrets.PROVIDER_KEY }}

Replace the provider URL and model, and add PROVIDER_KEY to your repository's Actions secrets. working-directory can name any prepared directory, including one outside a checkout. The GitHub action guide has complete workflows with and without checkout, output handling, and every input.

Agent integrations

The peen agent skill teaches an agent how to install and run Peen, send work over WebSocket, add workspace harness layers, and inspect stored state. It is documentation only. Installing it does not start a server, run a hook, or change a workspace.

Install it from the psyb0t/agents marketplace:

claude plugin marketplace add psyb0t/agents
claude plugin install peen@psyb0t

codex plugin marketplace add psyb0t/agents
codex plugin add peen@psyb0t

openclaw skills install @psyb0t/peen

Documentation

You want to Read
Start from zero Getting started
Install Peen, use the peen command, or run it by hand Deployment
Run turns and manage sessions from a shell Command line
Run a prompt in a GitHub workflow GitHub action
Use the browser chat Control surface
Decide where the agent runs and what it can touch Where it runs
Know what the agent can reach before you deploy Security
Configure providers, limits, and logs Configuration
Understand how Peen reads project files The harness
Give the agent project instructions and rules AGENTS.md and rules
Write named procedures the agent loads on demand Skills
Define child agents for contained jobs Named agents
React to background jobs, child agents, and outside systems Session events
Add hard checks or model instructions around actions Hooks
Give the agent the tools of MCP servers MCP servers
Build a WebSocket or REST client API reference, api/api.yml, and api/asyncapi.yaml
Embed Peen in a Go process Go embedding guide
See how it fits together and what it is built with Architecture
See how it does on coding benchmarks and what they found Benchmarks
Change Peen itself Development

Directories

Path Synopsis
Package api embeds Peen's OpenAPI document, the single source for the generated server, the Go client, and the web client's types.
Package api embeds Peen's OpenAPI document, the single source for the generated server, the Go client, and the web client's types.
cmd
benchrelay command
Command benchrelay forwards loopback TCP model traffic inside a networkless benchmark task container to the provider proxy's Unix socket.
Command benchrelay forwards loopback TCP model traffic inside a networkless benchmark task container to the provider proxy's Unix socket.
envexample command
Command envexample writes .env.example from the env file template.
Command envexample writes .env.example from the env file template.
repogen command
examples
embedding command
Command embedding runs one Peen turn inside this process against any OpenAI-compatible endpoint and prints the answer.
Command embedding runs one Peen turn inside this process against any OpenAI-compatible endpoint and prints the answer.
internal
app
pkg/agent
Package agent owns Peen's transport-independent agent runtime.
Package agent owns Peen's transport-independent agent runtime.
pkg/auditlog
Package auditlog adds a durable JSON sink beside the process logger.
Package auditlog adds a durable JSON sink beside the process logger.
pkg/config
Package config loads Peen's deployment configuration from PEEN_ variables.
Package config loads Peen's deployment configuration from PEEN_ variables.
pkg/config/envtemplate
Package envtemplate renders Peen's commented .env file.
Package envtemplate renders Peen's commented .env file.
pkg/contentblob
Package contentblob stores the repeated parts of a JSON document once, by content, and replaces them in the document with short references.
Package contentblob stores the repeated parts of a JSON document once, by content, and replaces them in the document with short references.
pkg/control
Package control owns the control surface's workspace policy and session registry.
Package control owns the control surface's workspace policy and session registry.
pkg/control/client
Package client is the local control client behind Peen's CLI commands.
Package client is the local control client behind Peen's CLI commands.
pkg/db
Package db opens Peen's SQLite database, applies its embedded migrations, and wires the generated gorm/gen repositories.
Package db opens Peen's SQLite database, applies its embedded migrations, and wires the generated gorm/gen repositories.
pkg/events
Package events carries typed notices about things that happened which the agent did not directly ask about: a process job ended, a child agent finished, or something outside Peen reported a change.
Package events carries typed notices about things that happened which the agent did not directly ask about: a process job ended, a child agent finished, or something outside Peen reported a change.
pkg/hooks
Package hooks runs validated layered hook actions at agent lifecycle points.
Package hooks runs validated layered hook actions at agent lifecycle points.
pkg/http/api
Package api provides primitives to interact with the openapi HTTP API.
Package api provides primitives to interact with the openapi HTTP API.
pkg/http/server
Package server exposes Peen's client-facing Serbewr HTTP API.
Package server exposes Peen's client-facing Serbewr HTTP API.
pkg/http/wsapi
Package wsapi holds Peen's generated WebSocket contract types, decoded and validated from api/asyncapi.yaml.
Package wsapi holds Peen's generated WebSocket contract types, decoded and validated from api/asyncapi.yaml.
pkg/mcptools
Package mcptools connects a session's worker to the MCP servers the operator configures, through elelem's mcp package.
Package mcptools connects a session's worker to the MCP servers the operator configures, through elelem's mcp package.
pkg/memlistener
Package memlistener is a net.Listener with no network address.
Package memlistener is a net.Listener with no network address.
pkg/metrics
Package metrics owns Peen's application Prometheus registry and its bounded runtime collectors.
Package metrics owns Peen's application Prometheus registry and its bounded runtime collectors.
pkg/naming
Package naming holds the shape rule for names Peen invents and owns: tool names, hook event names, and session event types.
Package naming holds the shape rule for names Peen invents and owns: tool names, hook event names, and session event types.
pkg/nondumpable
Package nondumpable keeps a Peen process's memory and environment away from other processes that run as the same user.
Package nondumpable keeps a Peen process's memory and environment away from other processes that run as the same user.
pkg/oneshot
Package oneshot runs one turn from the command line and exits.
Package oneshot runs one turn from the command line and exits.
pkg/pathglob
Package pathglob matches slash-separated relative paths against the glob patterns hook matchers and scoped rules share, so one pattern means the same thing in both.
Package pathglob matches slash-separated relative paths against the glob patterns hook matchers and scoped rules share, so one pattern means the same thing in both.
pkg/publicerror
Package publicerror turns an error into text that is safe to show a client.
Package publicerror turns an error into text that is safe to show a client.
pkg/runtimecontext
Package runtimecontext carries local embedding dependencies across calls.
Package runtimecontext carries local embedding dependencies across calls.
pkg/services/control-api
Package controlapi serves the control surface that control-core opened.
Package controlapi serves the control surface that control-core opened.
pkg/services/control-core
Package controlcore opens the control surface's durable state and runtime.
Package controlcore opens the control surface's durable state and runtime.
pkg/session
Package session owns Peen's durable transport-neutral session transcript.
Package session owns Peen's durable transport-neutral session transcript.
pkg/worker
Package worker is the boundary between Peen's control plane and the session-bound processes that actually run work.
Package worker is the boundary between Peen's control plane and the session-bound processes that actually run work.
pkg/worker/controlspace
Package controlspace launches a session worker in the control agent space, as a child process of the controller.
Package controlspace launches a session worker in the control agent space, as a child process of the controller.
pkg/worker/docker
Package docker launches a session worker as a psyb0t/peen sibling container.
Package docker launches a session worker as a psyb0t/peen sibling container.
pkg/worker/dockerproxy
Package dockerproxy is the read-only Docker Engine API proxy behind `docker: readonly`.
Package dockerproxy is the read-only Docker Engine API proxy behind `docker: readonly`.
pkg/worker/protocol
Package protocol carries Peen's private, session-bound worker protocol.
Package protocol carries Peen's private, session-bound worker protocol.
pkg/worker/run
Package run is the body of the internal `peen worker` command.
Package run is the body of the internal `peen worker` command.
pkg/worker/supervisor
Package supervisor owns the lifecycle of one controller's session workers.
Package supervisor owns the lifecycle of one controller's session workers.
pkg/worker/workerlog
Package workerlog carries a worker process's log records into the controller's own logging stack.
Package workerlog carries a worker process's log records into the controller's own logging stack.
pkg/workspacefs
Package workspacefs supplies the filesystem boundary shared by tools and harness discovery.
Package workspacefs supplies the filesystem boundary shared by tools and harness discovery.
pkg
http/api/client
Package client provides primitives to interact with the openapi HTTP API.
Package client provides primitives to interact with the openapi HTTP API.
peen
Package peen embeds the durable agent engine inside a Go process.
Package peen embeds the durable agent engine inside a Go process.
tests
testinfra
Package testinfra is the extendable integration-test harness for a servicepack app.
Package testinfra is the extendable integration-test harness for a servicepack app.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL