Picasso

Code Freely. Code Beautifully.

Picasso is a coding agent you can both *run* and *watch*. It ships as two surfaces over one engine: a terminal CLI/TUI (picasso, package @picassohq/cli) for people who live in the shell, and Picasso for Mac (1.0.54, Apple silicon, macOS 14+) for people who want to see the agent work: plan, tool calls, diffs and approvals, all visible. It is free and ad-supported through one clearly labelled sponsor line, with a free model and bring-your-own-key access to 25 built-in provider routes. The differentiators are a persistent memory layer, long-horizon goal mode with completion contracts, and a hard approval boundary: nothing touches your disk without passing the queue.

Both surfaces share the same engine, provider routes, settings, threads, memory, themes and trust model. The CLI is for speed and scripting; the Mac app makes the same work legible.

Status: pre-launch. Picasso for Mac ships as a signed, notarized DMG with silent updates; the CLI package is not published to npm yet and sign-ups are closed.

New here? Start with the quickstart, then the FAQ. What changed recently is in the changelog.

---

What Picasso is

• Free, ad-supported coding agent. No subscription. One labelled ◇ Sponsored line; sponsored content is never injected into model output, tool results or generated code.
• Two front ends, one engine. The terminal CLI/TUI and the native Mac app both run sessions on the Picasso engine, one process per session, against your real workspace. The engine is pinned (0.2.2-rc.1), lives in ~/.picasso/dsh-home and updates itself in the background with integrity checks and rollback.
• Persistent by design. A memory layer that compounds across sessions, synced sessions you can continue on another machine, and a replayable history. Past Claude Code, Codex and OpenCode sessions can be imported (history import).
• Bounded by default. Read only, Workspace write, Full access or Auto; every write and sensitive action goes through approvals; a sandboxed shell with per-domain egress rules.

---

Features: the shared engine

• Agent loop: plan → act → observe → reflect, with decisions and options cards when the agent needs you (01-agent-loop.md).
• Tools: file edits, shell, search, web fetch, reading public X through x.md, and deferred tools reached on demand (02-tools.md).
• Subagents: fan-out/fan-in with named roles and isolated contexts; /subagent, /fleet or @role (03-subagents.md).
• Plan mode: read-only planning with a review before anything changes (04-plan-mode.md).
• Goal mode (`/goal`): long-horizon runs with completion contracts and verified evidence, in visible rounds (16-goals.md).
• MCP and app connections: an on-demand MCP gateway, Connect an app (Blender, Figma, browser automation, Xcode, iOS Simulator, x.md) and a measured per-turn cost for every extension (05-mcp.md).
• Persistent memory: codebase facts, style and decisions, never sent outside your account (15-memory.md, memory quickstart).
• Sessions: resume, fork, undo, rewind, replay, archive, a librarian that files threads into projects, My Work, and a turn-by-turn context timeline (06-sessions.md).
• Providers and models: 25 built-in routes plus any compatible gateway, every model's context window, output limit and reasoning levels (picasso models), and ordered connections with fallback (07-providers.md).
• Sandbox and approvals: shell allowlist, network egress control, approval on write (08-sandbox.md).
• Hooks, commands and schedules: lifecycle hooks, 83 slash commands, and local schedules that keep running with the resident runner (09-hooks-and-commands.md).
• Auth and accounts: device-code sign-in (11-auth-and-accounts.md).
• Ads: one labelled sponsor line, always disclosed (13-ads-monetization.md).
• Telemetry: opt-in and schema-documented (12-telemetry.md).
• Cache-aware context: stable prompt prefixes and cache evidence (18-cache-harness.md).

---

Features: the CLI / TUI

The terminal surface (10-tui.md; design in design/):

• A start page with your activity heatmap, GitHub or GitLab contributions and recent threads (/activity, /customize), and a short /tour.
• Queue, steer and interrupt a running turn; Enter in an empty composer sends a queued message now.
• 83 slash commands with a fuzzy palette, 13 colour themes shared with the Mac (/theme), reduced motion and an accessible mode.
• Scriptable runs (picasso run, picasso -p with JSON and stream-JSON), plan mode, subagents and goals from the shell; picasso service keeps threads and schedules running after the terminal closes.
• Distribution and updates: 14-distribution.md (picasso update).

---

Features: Picasso for Mac

The native app (apps/mac) makes the same engine visible. Every surface is reachable from the sidebar or the ⌘K command palette:

• Studio: the start page ("What should we build in ‹project›?", or start without a project), model choice in the headline with Auto, a quiet chip row (checkout, branch, permission), a labelled activity heatmap, GitHub/GitLab contributions and Recent; Customize reorders the cards. Backdrops: Aurora, Dots, Plain, Image or Horizon.
• Threads: grouped Needs you / Working / Settled, one-click Archive with Undo, a project / title breadcrumb, a worktree per thread by default.
• Thread view: queue, steer (your steers show as your own messages), interrupt; decisions and options cards; What changed per command with Copy summary; failed commands marked ✕.
• Inspector: Overview, Changes, Preview, Context (Overview / Timeline) and background processes with status, command and output.
• Projects: open, clone, pin; each project wears an initials tile in its own colour.
• Librarian, My Work, Schedules: auto-filing for threads started without a project, every file your sessions made (Make a similar one), and local schedules.
• Extensions: plugins, MCP servers, skills and app connections with measured per-turn cost and data access; third-party items ask once.
• Settings (in the main window): General (keep threads running when Picasso quits, engine updates, What changed defaults), Providers (API-key sign-in opens the key page; model connections; provider sync), Permissions, Appearance (13 themes), Advanced, Safety, Account, Local Helper, About.
• Help: Take the tour, install by asking your agent, and what Picasso puts on your Mac (footprint).

The command → route → action mapping is apps/mac/Picasso/Core/CommandManifest.swift, which reads the bundled copy of packages/commands/command-manifest.json.

---

Build Specification

This directory is also the complete build specification: PRD, architecture, brand framework, competitive teardown, milestone-grouped task list, pre-GA checklist, and the locked visual design system from Claude Design. A subagent fleet can begin execution against tasks.md on day one.

Name

The name is Picasso. Wordmark is picasso set lowercase in Editorial New italic (licensed migration 2026-10-16; originally specified as Instrument Serif) with a Klein-blue dot trailing the baseline. Command is picasso (full) or pic (alias). Tagline: _Code Freely._ See brand.md for the framework and design/INTEGRATION.md for the visual treatment.

The eliminated names listed in brand.md exist as a historical record so nobody re-proposes them; do not revisit. Final trademark clearance proceeds in parallel with M0 build; if Picasso fails clearance the fallback is Fair Use (the framework transfers cleanly, the design tokens stay).

File map

cli-build/
├── README.md                       This file.
├── EXECUTE.md                      Master execution prompt. Feed this to Claude Code / Codex / Picasso.
├── competitive-teardown.md         Refined matrix of 19 competitor CLIs + steal list.
├── brand.md                        Brand framework, voice, wordmark, candidate clearance criteria.
├── architecture.md                 Monorepo layout, stack, package boundaries, build pipeline.
├── tasks.md                        Milestone-grouped, dependency-ordered task list with acceptance criteria.
├── checklist.md                    Flat, tickable pre-GA checklist across brand, legal, security, launch.
├── design/                         Locked visual design system from Claude Design.
│   ├── INTEGRATION.md              Hand-off brief — read before implementing the TUI.
│   ├── styles.css                  Design tokens (colors, type, motion, surfaces). Source of truth.
│   ├── tui-primitives.jsx          Component primitives — names and props match Ink implementation.
│   ├── scenes-a.jsx                Scenes 01–05 (First Light, Canvas, Plan, Goal, Subagents).
│   ├── scenes-b.jsx                Scenes 06–10 (Memory, Studio, Palette).
│   ├── scenes-c.jsx                Scenes 11–14 (Replay, Approval Gate, Sponsored, Paper period).
│   ├── Picasso TUI.html            Renderable artboard view of every scene.
│   └── design-canvas.jsx           Figma-style canvas wrapper for the artboards.
└── docs/                          PRD specs (00–19), this README, and reference/authoring guides — all flat in docs/.
    ├── 00-overview.md              Vision, positioning, business model, success metrics.
    ├── 01-agent-loop.md            Plan / act / observe / reflect. Depth limits. Error recovery.
    ├── 02-tools.md                 Tool catalog and call protocol. Tool registration API.
    ├── 03-subagents.md             Fan-out / fan-in. Named roles. Isolated contexts. Result merging.
    ├── 04-plan-mode.md             Plan generation. Approval gates. Auto-accept thresholds. plan.md format.
    ├── 05-mcp.md                   MCP client + server. Curated registry. mcp install UX. ACP service mode.
    ├── 06-sessions.md              Persist / resume / fork / replay. Named threads. Web dashboard.
    ├── 07-providers.md             Provider abstraction. Per-task routing. Budget caps. Fallback chain.
    ├── 08-sandbox.md               Shell allowlist. Network egress. Approval-on-write. OS sandboxing.
    ├── 09-hooks-and-commands.md    Pre/post hooks. Slash commands. User-defined commands.
    ├── 10-tui.md                   Terminal UI spec. Implements the design system in design/.
    ├── 11-auth-and-accounts.md     Device-code flow. Account / org / team scopes. SSO.
    ├── 12-telemetry.md             Opt-in. Anonymized. Collection schema. Privacy guarantees.
    ├── trajectory-data-policy.md   Free-tier automatic capture under accepted Terms. Evaluation is not release. Legal gate.
    ├── 13-ads-monetization.md      The wedge. ZeroClick + TryGravity adapters. Ad SDK. Disclosure rules.
    ├── 14-distribution.md          npm. brew. curl-pipe-bash. Windows installer. Signing.
    ├── 15-memory.md                Persistent memory layer (Supermemory-inspired). Codebase, style, decisions.
    ├── 16-goals.md                 /goal long-horizon autonomous mode. Completion contracts. Multi-hour runs.
    ├── 17-subscription-passthrough.md   Use existing Claude / ChatGPT subscriptions for inference.
    ├── 18-cache-harness.md              V2 cache-aware prompt/context harness, provider hints, and episode evidence.
    └── 19-master-backend.md             Master-backend / admin control plane (orgs, budgets, flags, audit).

Standards

• No MVP language. Every feature ships in v1. Roadmap is for v2 only.
• Apple-caliber copy in brand, taglines, error strings, every user-facing surface. Voice rules in brand.md are non-negotiable.
• Pixel-by-pixel fidelity to `design/`. The design system in design/styles.css is the source of truth for colors, type, motion, and surfaces. PRD files describe behavior; the design system describes how it looks.
• Cite the source. Where a feature is borrowed from a competitor, the source is footnoted in competitive-teardown.md.
• Parallelize. Where research, drafting, or scaffolding can run as concurrent subagents, do that.
• Hard product rules (never violable): no injection of sponsored content into model output, tool results, or generated code; ad surfaces always unambiguously labeled with the ◇ Sponsored eyebrow; memory layer never silently exfiltrates code outside the user's account.

Reading order

For a reviewer: 00-overview.md → design/INTEGRATION.md → 13-ads-monetization.md → 15-memory.md → 16-goals.md → 17-subscription-passthrough.md → 18-cache-harness.md → competitive-teardown.md → tasks.md.

For a subagent fleet implementing the TUI: open design/Picasso TUI.html alongside 10-tui.md. The HTML is the visual spec, the markdown is the functional spec; both must be true.

For a subagent fleet implementing everything else: tasks.md → grouped PRD files per milestone → checklist.md for pre-ship gates.

For the orchestrator running the autonomous build: feed EXECUTE.md to Claude Code, Codex, or Picasso itself (once M0 is up). It owns the full build loop — reads the spec, maintains build-state.md, spawns parallel subagents, and stops only when every gate in checklist.md is green.