Picasso Docs

The coding agent for the terminal and the Mac.

Install Picasso, connect a provider, and learn the terminal app and Picasso for Mac: memory, goals, history import, and what Picasso keeps on your machine.

Get started

Guides

TUI

The terminal user interface: picasso with no command (or picasso tui) opens it. This page is the functional reference for what ships on main: how the screen is laid out, how you ta

Keyboard Shortcuts

This document is generated from packages/tui/src/keyboard.ts.

Providers

Picasso runs every model call through one of two credential modes. Subscription sign-in is not available at launch ([17](17-subscription-passthrough.md) is post-launch).

Memory Quickstart

Initialize project memory and run the first recall query.

15 - Memory

The persistent memory layer. The agent does not start cold every session. It remembers the codebase's architecture, the developer's coding style, and the decisions that were made a

/goal Quickstart

Run a bounded long-horizon goal in under five minutes.

Goals

The /goal long-horizon autonomous mode. Provider-agnostic. The agent runs until a completion contract is satisfied — minutes, hours, or days — planning, acting, testing, and self-c

Goal Contract Reference

A goal contract (@picasso/goals GoalContract) defines what Picasso should finish, where it may work, how much budget it may spend, and — critically — how completion is judged by ma

History import

Picasso can bring in past sessions from Claude Code, Codex and OpenCode as read-only threads. The code is packages/sessions/src/history-import (@picasso/sessions/history-import), s

Remote engines (cloud fleet)

Picasso can run threads on more than one engine: the bundled engine on this Mac plus remote engines you start yourself on another host — a workspace VM, a build box, a devcontainer

Auth and Accounts

A Picasso account is needed only for managed inference, memory sync, cloud sessions and the account dashboard at https://picassohq.com/account. Bring-your-own-key runs work without

Migration Guide

Move from existing coding agents to Picasso without losing workflow shape. Signing in with a Claude or ChatGPT subscription is not available in this release; use an API key, a rout

How Picasso works

OverviewA coding agent with the harness depth of Claude Code, Codex, Droid, Cursor, and Devin, given to developers free of charge, supported by honestly disclosed ad inventory. It ships asAgent LoopThe plan-act-observe-reflect loop. Every turn the agent takes is one trip through this cycle. Depth and step caps prevent runaway loops. Error recovery is deterministic. Hooks fireToolsThe tool catalog the agent has access to. Every tool exposed to the model is registered through the same interface, validated by the same schema layer, and executed through the samSubagentsParallel subagents with independent context windows, named roles, and structured fan-out/fan-in semantics. The harness pattern proven in Devin's parallel cloud agents and Qwen Code04 - Plan ModeRead-only software architect mode. /plan maps a repository, diagnoses the request, and produces a reviewable strategy document with rationale, impact boundaries, risks, and next stMCPNative Model Context Protocol client and server support. A curated registry of trusted MCP servers. One-line install UX. The agent extends itself the same way Claude Code, Crush, KSessionsThe state model. Every interaction with the agent is a session. Sessions persist, resume, fork, and replay. The CLI and the Mac app read the same session store on this Mac. Attach SandboxDefense in depth. Every tool call that touches the filesystem, shell, or network executes inside a sandbox. Workspace-root containment by default, OS-level isolation when availableHooks and CommandsExtension surfaces that let users customize agent behavior without forking the codebase. Hooks fire at well-defined transitions in the loop. Slash commands extend the TUI's keyboarTelemetryTelemetry ingestion is off at launch (GL-36). Nothing is collected or sent:Telemetry SchemaThis document is generated from packages/telemetry/src/public-schema.ts.Ads & MonetizationThe wedge. Every other coding-agent CLI is a subscription product with a free trial. Picasso is a free product with sponsored surfaces, honestly disclosed. ZeroClick and TryGravityDistributionPicasso launches on two channels:Subscription Passthrough (post-launch)> Not available at launch. Credential modes at launch are BYO key and managed. This document describes planned work; the CLI flags and OAuth client are not live. ChatGPT sign-in ne

Extend Picasso

For contributors

ArchitectureSystem architecture, monorepo layout, language choices, build and release pipeline, and the package boundaries a subagent fleet builds against.CLI & TUI Architecture> Source Specs: cli-tui-beautify-plan.md, cli-tui-production-readiness.md, docs/10-tui.md, docs/20-dsh-runtime-adoption.md, docs/TUITERMINALEQUIVALENCE.mdMac App & Desktop-Helper Relay Architecture> Source Specs: mac-swift-prd.md, mac-app-beautify-plan.md, mac-ux-9-prd.md, docs/22-remote-engines.md, dsh-plugin-ecosystem.mdLean-Context Architecture (Two-Tier Progressive Disclosure)> Source Specs: lean-context-prompt.md, v2-cache-harness-prd.md, dsh-plugin-ecosystem.mdDSH Plugin Ecosystem & Shared Patch Architecture> Source Specs: dsh-plugin-ecosystem.md, docs/20-dsh-runtime-adoption.md, docs/21-dsh-adoption-spike.md, handoff.mdCache HarnessPicasso v2 treats caching as a harness problem, not only a provider feature. Providers can discount or reuse repeated prompt prefixes, but Picasso owns the decisions that make thosCache Harness & Prompt-Cache Probe> Source Specs: v2-cache-harness-prd.md, docs/18-cache-harness.md, lean-context-prompt.md, docs/cache-harness-threat-model.mdCache Harness Threat ModelThis threat model covers the v2 cache harness: prompt sections, context packs, cache policies, provider cache hints, trajectory records, and episode packages.DeepSeek Harness Runtime AdoptionStatus: Decision — adopted; Phases 0–4 COMPLETE (2026-08-16): the dsh runtime is the PERMANENT DEFAULT (legacy AgentLoop deleted; createDshAgentLoop the single factory; auto-resolu

Reference

Public package APIs

@picasso/ads-sdk62 exports from packages/ads-sdk@picasso/auth64 exports from packages/auth@picasso/auth-bridge0 exports from packages/picasso-auth-bridge@picasso/auto-approve0 exports from packages/picasso-auto-approve@picasso/browser0 exports from packages/picasso-browser@picasso/cache-harness108 exports from packages/cache-harness@picasso/cache-probe0 exports from packages/picasso-cache-probe@picasso/checkpoints0 exports from packages/picasso-checkpoints@picasso/commands64 exports from packages/commands@picasso/commands-bridge0 exports from packages/picasso-commands@picasso/contributions242 exports from packages/contributions@picasso/control-plane32 exports from packages/control-plane@picasso/core312 exports from packages/core@picasso/desktop-git40 exports from packages/desktop-git@picasso/desktop-ipc69 exports from packages/desktop-ipc@picasso/desktop-projects25 exports from packages/desktop-projects@picasso/desktop-schedules26 exports from packages/desktop-schedules@picasso/desktop-sponsors29 exports from packages/desktop-sponsors@picasso/desktop-voice13 exports from packages/desktop-voice@picasso/goals182 exports from packages/goals@picasso/hooks33 exports from packages/hooks@picasso/integration-contracts335 exports from packages/integration-contracts@picasso/lean-context0 exports from packages/picasso-lean-context@picasso/librarian0 exports from packages/picasso-librarian@picasso/lifecycle-hooks0 exports from packages/picasso-lifecycle-hooks@picasso/llm-adapter0 exports from packages/picasso-llm-adapter@picasso/mail0 exports from packages/picasso-mail@picasso/mcp98 exports from packages/mcp@picasso/memory258 exports from packages/memory@picasso/memory-recall0 exports from packages/picasso-memory@picasso/model-router0 exports from packages/picasso-model-router@picasso/options0 exports from packages/picasso-options@picasso/picasso-hooks-bridge0 exports from packages/picasso-hooks@picasso/plan-mode31 exports from packages/plan-mode@picasso/pr-watch62 exports from packages/pr-watch@picasso/progress-reports0 exports from packages/picasso-progress-reports@picasso/provider-models0 exports from packages/picasso-provider-models@picasso/providers175 exports from packages/providers@picasso/repo-index0 exports from packages/picasso-repo-index@picasso/sandbox82 exports from packages/sandbox@picasso/schedule-pause0 exports from packages/picasso-schedule-pause@picasso/sdk-server0 exports from packages/picasso-sdk-server@picasso/secrets44 exports from packages/secrets@picasso/session-lifecycle0 exports from packages/picasso-session-lifecycle@picasso/sessions196 exports from packages/sessions@picasso/shared70 exports from packages/shared@picasso/shared-home295 exports from packages/shared-home@picasso/subagents19 exports from packages/subagents@picasso/telemetry69 exports from packages/telemetry@picasso/tools99 exports from packages/tools@picasso/trackers0 exports from packages/picasso-trackers@picasso/tui525 exports from packages/tui@picasso/x-reader8 exports from packages/picasso-x-reader