PrAImate

Official source and releases: sPROFFEs/PrAImate

PrAImate 1.2.2 is a GUI-only desktop harness for Claude Code, OpenClaude, Codex CLI, OpenCode, and the bundled PrAImate Code build. It gives those CLIs one place for coding terminals, chats, reusable agents, workflows, skills, locally configured MCP servers, local-model routing, privacy controls, and optional Git backup.

PrAImate does not replace the underlying CLI or model provider. The selected CLI still performs the model request, owns its native authentication, and may keep its own session/configuration files.

Supported systems

• Linux amd64 (release archive)
• Windows amd64 and arm64 (release archives)
• Linux arm64 source builds where the required native WebKitGTK toolchain is available

macOS is not a supported or published target. The old Bubble Tea TUI is no longer shipped; running praimate opens the desktop application.

Install

Linux:

curl -fsSL https://raw.githubusercontent.com/sPROFFEs/praimate/main/scripts/install.sh | bash

Windows PowerShell:

iwr -useb https://raw.githubusercontent.com/sPROFFEs/praimate/main/scripts/install.ps1 | iex

Useful commands:

praimate                # open the desktop application
praimate code           # launch the managed PrAImate Code CLI
praimate agent run --agent DEV-TEAM --cli praimate-code --folder /project --prompt "review this code"
praimate -check-update  # check the latest GitHub release
praimate -update        # update the installed release
praimate -version       # print version and platform

Headless agent runs are a versioned machine interface: JSON is written to stdout and diagnostics stay on stderr. Use --output jsonl for live events, use a protected --prompt-file to keep large/sensitive text out of the process list, or use --workflow with repeatable --input key=value parameters. A caller-supplied --run-id enables encrypted status lookup and idempotent result replay. Add --persist only when the run should appear in Chats. The default --tools safe policy is read/answer-only; edits and full are explicit automation trust decisions. When the database password is not remembered, an interactive terminal prompts for it with input echo disabled. See the CLI agent API guide and Python example.

The installer supports binary/source, user/system, and uninstall modes:

./scripts/install.sh --binary
./scripts/install.sh --source
./scripts/install.sh --user
./scripts/install.sh --system
./scripts/install.sh --uninstall
./scripts/install.sh --uninstall --purge

.\scripts\install.ps1 -Mode Binary
.\scripts\install.ps1 -Mode Source
.\scripts\install.ps1 -AllUsers
.\scripts\install.ps1 -Uninstall
.\scripts\install.ps1 -Uninstall -Purge

Normal uninstall keeps PrAImate data. Purge removes it.

First launch and encrypted storage

The first GUI launch requires a database password of at least 12 characters. PrAImate generates a random 512-bit SQLite encryption key and wraps it with XChaCha20-Poly1305 under an Argon2id-derived password key. The database itself uses AES-256-XTS.

On later launches:

• without Remember on this device, the password is required again;
• with it enabled, Windows Credential Manager or the Linux desktop Secret Service stores the password for automatic unlock;
• Settings → Data and privacy can forget that stored credential.

The raw database key exists only in the unlocked process. Losing the password means losing the encrypted database and encrypted backup snapshots.

All PrAImate-owned persistent data is centralized under:

System	Data root
Linux	$XDG_CONFIG_HOME/praimate or ~/.config/praimate
Windows	%APPDATA%\praimate

This root contains the encrypted database and key envelope, non-secret bootstrap configuration, agents, skills, managed tools, and managed-run state (runs/<run-id>/request.json, status, transcript checkpoint, per-run memory, and artifacts). A user-selected projects/workspaces folder remains separate.

Managed-run JSON and artifacts are permission-restricted ordinary files, not records inside the encrypted database. They are not included in Git backup. Anyone who can read the operating-system account's PrAImate data folder can read them.

Saved Local LLM and MCP credentials live in the encrypted database. PrAImate does not create application, Graphify-query, or terminal-output log files. Underlying CLIs may still keep native logs or sessions.

Desktop pages

Page	Purpose
Code	Run a supported CLI live in a chosen project folder, with optional model, local endpoint, agent context, and MCP wiring.
Chats	Create clean conversations, configure per-chat CLI/model/tools/skills/MCP, and reopen saved chat, studio, code, or legacy workspace sessions.
Agents	Create, edit, import/export, and run YAML agents and workflows; manage raw or Graphify-backed knowledge.
Skills	Enable built-in skills or add a skill from a URL, local ZIP, or manual definition.
CLI & Tools	Detect, install, update, or repair supported CLIs and managed tools.
Local LLM	Save an OpenAI-compatible endpoint, API key, and model; route supported CLIs and see an explicit warning for HTTP transport.
MCP	Add, edit, enable, or remove locally configured stdio/HTTP MCP servers and local catalogue entries.
Settings	Updates, source builds, appearance, Git backup, and storage/privacy controls.
About	Version, platform, encryption status, paths, compatibility, and the full privacy disclosure.

Agents and workflows

Agents are portable YAML definitions. They can contain:

• instructions and supported CLIs;
• tool policy and allowed surfaces;
• mcp_servers references;
• one or more parameterized workflows;
• a default workflow;
• raw or Graphify/RAG knowledge mode;
• an optional, explicitly confirmed requirements installation script.

Agent Studio starts with Guided, Manual, and Import paths. Guided creation turns a purpose, knowledge choice, and explicit capability checklist into a deterministic Simple, Tool-enabled, or Autonomous preset. The result is always reviewable as agent.yaml plus an optional runtime.json.

Agents with knowledge, requirements, or runtime capabilities are exported as .praimate-agent packs. The pack contains agent.yaml, optional runtime.json, knowledge/**, and requirements/**. Import validates and stages the complete pack before replacing live data. Agents without a runtime manifest keep the existing native CLI behavior.

Simple and Tool-enabled presets run through the current native CLI path. Autonomous runs use a managed single-agent lifecycle in Chats, document Studio, and Workflows. The runtime provides explicit completion, structured per-run working memory, artifacts, bounded context/output, live events, and durable checkpoints. Declared capabilities expose brokered project read/search/write, Git, argv-only commands, bounded HTTP GET, Raw or Graphify RAG knowledge, and configured MCP tools. File writes, commands, mutating Git, network requests, and MCP connection/tool calls pause for explicit approval. The underlying CLI remains in safe mode and never receives those host tools directly.

Stopped, failed, stalled, and crash-interrupted runs can resume from Agent Studio. If interruption occurred during a tool call, PrAImate records its outcome as unknown and tells the agent to inspect current state before retrying. Run checkpoints are functional state, not diagnostic/event logs.

The Autonomous preset does not claim OS-level sandbox isolation: an approved command is still a real process on the host. Team/delegation and manifests that claim sandbox remain fail-closed. Team is not offered in guided creation until that coordinator exists. Interactive Terminal execution remains native.

Skills are not currently embedded in agent packs. They remain independently managed, CLI-tagged resources selected per chat.

MCP

PrAImate exposes only MCP servers you configure or install locally:

• stdio servers run a local command or container;
• HTTP servers point to an endpoint you control;
• environment values are stored in the encrypted database;
• servers can be edited after creation;
• enabled servers are selected per chat, or referenced by an agent's mcp_servers YAML field.

The local catalogue is a convenience list of locally launched utilities, not a directory of third-party hosted services.

Local LLM routing

The Local LLM page accepts Ollama, vLLM, GPUStack, LiteLLM, llama.cpp, LocalAI, and similar OpenAI-compatible endpoints.

PrAImate can configure:

• OpenClaude through per-launch OpenAI-compatible environment variables;
• OpenCode/PrAImate Code through their provider configuration plus environment-based secrets.

Claude Code stays on its supported Anthropic transport. Use OpenClaude for Claude-style agents backed by a local model. PrAImate also does not modify Codex provider configuration; Codex uses whatever provider and authentication the user configured directly in Codex.

If an endpoint uses http://, the GUI warns that the underlying CLI will send model traffic over unencrypted HTTP. PrAImate cannot add HTTPS to a server that does not provide it.

Execution reliability

Chat, Studio, workflows, and live Code terminals use the same backend launch resolver. Before a run starts, PrAImate validates the CLI, agent surface, working folder, local route, permission level, and referenced MCP servers. Launch dialogs show the selected CLI's effective capabilities and block invalid configurations before any child process starts.

Permission levels are capability-based. Unsupported levels are visibly reduced to safe mode instead of being silently promoted. Workflow runs default to safe mode and never force full tool access.

Agentic runs use a separate managed path rather than replacing the workflow runner. Its policy broker exposes only capabilities declared by the agent: project read/search/write, Git, argv-only commands, bounded HTTP GET, Raw or Graphify knowledge, configured MCP tools, working memory, and artifacts. Mutating or external operations pause for explicit GUI approval; MCP configuration and credentials remain backend-only. Plain model prose cannot finish a managed run: completion requires the runtime's explicit finish action. Large continuation or final output is shortened in the model/UI context and preserved as a text artifact.

Memory and sessions

The removed cross-chat Memory GUI/database feature is not part of PrAImate. PrAImate does not build an episodes/facts/identity memory profile across unrelated conversations.

Autonomous working memory is scoped to one managed run. It persists only so the user can inspect that run in Agent Studio; it is not injected into other chats or later runs and does not recreate the removed cross-chat memory feature.

Existing workpath chats may still use their own per-chat MEMORY.md. That file is ordinary workspace content staged into the chat sandbox and synchronized back after a session. It is intentionally separate from the removed cross-chat memory feature.

The underlying CLI owns communication and native resume. PrAImate records the session metadata needed by its GUI and, for legacy workspace chats, can mirror the relevant native session slice into the chat folder for portability.

Git backup

Backup is optional and disabled until configured. Settings offers two explicit starting points:

1. create local Git history, optionally with a new remote;
2. connect to and compare an existing remote before choosing how to reconcile.

PrAImate uses the installed git client and its existing HTTPS/SSH credentials. Its own backup commits use the repository-local PrAImate <praimate@local> identity, so global Git author configuration is not required or modified.

The database backup consists of:

• .praimate-state/db.sqlite — encrypted snapshot;
• .praimate-state/db.sqlite.key — password-protected key envelope.

A second Windows or Linux installation can import it when opened with the same database password. Workspace files, transcripts, native session slices, and per-chat MEMORY.md files are normal Git objects, not encrypted vault content.

Important for upgrades: older backup commits may contain plaintext SQLite snapshots. Creating encrypted snapshots does not erase those historical Git objects. Recreate the backup repository or rewrite its history if old plaintext snapshots must be removed.

Delete all stored data

Settings → Data and privacy → Delete all stored data uses two confirmation steps. It removes PrAImate's data root, encrypted database, key envelope, settings, agents, skills, managed tools, remembered database credential, and PrAImate-managed CLI routing blocks. The projects/workspaces folder is shown explicitly and can be included or kept.

After deletion the app quits. Opening it again starts with a clean database and first-run setup.

Build

Linux source builds require Go, Node/npm, pkg-config, GTK 3, and WebKitGTK 4.1:

sudo apt-get install -y npm pkg-config libwebkit2gtk-4.1-dev libgtk-3-dev

Build the supported release bundles:

scripts/build.sh --version=1.2.2
scripts/build.sh --version=1.2.2 --with-code --with-graphify

Build PrAImate Code from the vendored OpenCode source:

PATH="$HOME/.bun/bin:$PATH" \
  OUT="dist/$(go env GOOS)-$(go env GOARCH)" \
  scripts/build-praimate-code.sh

See docs/RELEASE-GITHUB.md for the complete release asset matrix and checksum process.

Documentation

Document	Scope
Full guide	Installation, every GUI page, storage, privacy, agents, skills, MCP, local LLMs, sessions, backup, and deletion.
Agent creation manual	Create, configure, test, package, and share agents; complete praimate.agent/v1 YAML reference.
Workpath quickstart	Create and compile a workpath with wpc.
Workpath schema	Source files, imports, hooks, tools, and subagents.
Compile targets	Files produced for each wpc target.
Activation	Where compiled files must be placed for each host CLI.
Release guide	Supported release targets, artifacts, checksums, and publication.

License

MIT