Local Claude CLI chat and Write-only hosting is enabled by default in normal Pipkin desktop launches, with CLI 2.1.299 or newer (stable releases). Configure Settings → Connections → Claude Code · local CLI, then choose a CLI model in the ordinary model picker alongside native providers. Installation/project discovery needs no typed paths; setup failure never substitutes another provider or disables unrelated conversations. No experimental flags are needed. Explicit trust and review remain required. This is not a sandbox, billing guarantee or full tool parity.
A faster way to AI, for developers.
A native desktop coding agent with a built-in Rust engine and GPUI interface.
The window above is the built-in demo (a simulated agent, marked "Demo · simulated agent" in the app).
On Linux x86_64 (Arch / Omarchy and other distributions), this is the simple way to get Pipkin:
curl -fsSL https://github.com/last-refuge/pipkin/releases/latest/download/install.sh | bashIt downloads the prebuilt archive of the latest release, checks it against the release's SHA256SUMS, and
installs it into ~/.local. No root, no build, no external runtime. On Omarchy, press Super+Space
and type "Pipkin". Run the same line again to upgrade. Everything else, including macOS, installing by hand and
building from source, is under Install.
Pipkin combines a built-in coding engine with a fast native interface: streaming answers, tool calls you can read at a glance, a view of the project's working-tree changes, and a composer that saves drafts with visible save status. It is a real application, not a web view: one Rust binary, GPU-drawn, with its own text editing, selection and accessibility tree.
1.1.0. Built and used daily on Arch / Omarchy (Hyprland, Wayland), which is the one supported platform. It runs a built-in Rust engine. macOS builds are experimental, and some of the accessibility and scaling checks that need a person at a machine are still open. See Status and the changelog before you rely on it.
Work with the agent
- Streaming conversations with Markdown, syntax-highlighted code and one-click copy.
- Tool calls as quiet, slim lines: a plain verb ("Reading files", "Editing files", "Running"), what they act on, and a check, spinner or failure. A run of steps folds to one line ("Read 2 files, edited 1 file, ran 3 commands" plus the latest command) with a chevron at the end; click it to show every step and follow along live. The model's thinking is a one-line summary you can open. Expand any step for its full output, saved or copied in full even when long.
- Steer a run in progress, queue a follow-up, stop it, and pick it back up after a restart. The engine owns the queue, so what you see is what will run.
- Attach files by picker or by dropping them on the window; choose the model from the engine's catalog.
- Native subagents are included by default, with child status and transcript previews. Preferences → Allow subagents blocks new calls without cancelling ongoing work.
- Legacy profile extensions are outside Pipkin's scope. Historical extension metadata is preserved during import without loading extension code; see compatibility.
See what changed
- A changes pane with a diff card (line numbers, additions and removals) and a "Files changed" list with M / A / D badges and counts.
- Open the selected file in your editor, or a terminal in the project, from the pane.
Keep work recoverable
- Drafts are saved as you type; a send is journalled before dispatch and reconciled with the engine after a crash or lost connection. Uncertain outcomes are not blindly resent. This does not guarantee exactly-once external tool effects; see recovery semantics.
- Conversations are cached on your machine: without the engine they still open, read and search, clearly marked as saved copies.
- Search messages across everything saved, and page back through history past a compaction.
Feels native
- A brand-true dark theme and a light one, Poppins throughout, text sizes, reduced motion, keyboard-first.
- Remembers your window size and pane widths. IME and accessibility integration exist, but native qualification is partial and typed-character screen-reader speech remains a failing/unverified gate; see Status.
![]() |
![]() |
| Tool calls at a glance | Every change, with its diff |
![]() |
![]() |
| Ready when you are | Light theme |
The one-line installer is the recommended way on Linux x86_64. The sections below cover what it does, installing by hand, macOS, building from source and managing an installed Pipkin.
curl -fsSL https://github.com/last-refuge/pipkin/releases/latest/download/install.sh | bashThe script downloads the prebuilt archive named in the latest release's SHA256SUMS, verifies the checksum,
unpacks it and runs the archive's own installer into ~/.local. It never compiles anything: on a Mac, another
architecture or a release without a Linux archive it stops and says what to do instead. It needs curl, tar,
zstd and sha256sum, asks for no password and sends no credentials. The script is short and lives
in this repository; read it first if you like, or run it with --dry-run.
| Option | Effect |
|---|---|
--version 1.1.0 |
install that release instead of the latest |
--prefix DIR |
install somewhere other than ~/.local |
--dry-run |
show what would happen and change nothing |
--list |
list the installed versions |
--rollback |
reactivate the previous version in one step |
--uninstall |
remove Pipkin; your data in ~/.local/share/pipkin stays |
Pass options after bash -s --, for example:
curl -fsSL https://github.com/last-refuge/pipkin/releases/latest/download/install.sh | bash -s -- --dry-runThe supported platform is x86_64 Arch/Omarchy, Hyprland/Wayland with a Vulkan-capable GPU driver. Other desktops, distributions and X11 are experimental, and native ABI compatibility follows the release's build inputs. The installed package is the app and engine in one Rust binary; it keeps versioned binaries, performs an offline engine handshake before activating a version, and preserves application data across upgrades and rollbacks. Releases are checksummed but not signed. Database rollback needs compatible schemas or the documented backup restoration; see packaging.
Release archives are on GitHub Releases: the Linux x86_64
archive with its installer, the experimental macOS DMG/ZIP for Apple Silicon and Intel, build-info-*.json,
install.sh and one SHA256SUMS. Check the checksum before installing.
sha256sum --check --ignore-missing SHA256SUMS
tar --zstd -xf pipkin-native-<version>-x86_64.tar.zst && ./install.sh # Linux: into ~/.local, no root neededFor a pacman-managed Arch package instead of the per-user installer, see the advanced instructions in getting started.
Download the DMG for your Mac, open it and drag Pipkin to Applications. The app is ad-hoc signed and not notarized, so Gatekeeper warns on first launch, and no interactive acceptance has been run on a Mac. See macOS notes.
Install your platform's native build prerequisites once, then:
git clone https://github.com/last-refuge/pipkin.git && cd pipkin
scripts/setup.sh --run # build the native app/engine, check, launchNo external engine checkout, patches, npm install or server startup. Subagents are included by default. The launcher selects this checkout as the project so you can use Pipkin to build Pipkin.
scripts/run.sh # run the last successful native build again
scripts/setup.sh --install # install for your user: Linux ~/.local; Mac ~/Applications/Pipkin.app
scripts/setup.sh --check # check prerequisites only; no downloads or installationMac source builds support Apple Silicon/Intel. Linux source setup targets glibc x86_64 (Arch/Omarchy, Debian/Ubuntu/Fedora prerequisites are documented; other desktops remain experimental). The script never runs sudo or installs Node/npm. Each rebuild stages an immutable native binary, so you can build while the old app runs; Quit and relaunch to use the new build. See the complete source setup and self-development guide.
Native credentials and configuration live separately from legacy profiles; --pi-agent-dir DIR selects an import source.
The built-in engine supports explicitly managed native hosts; see native attachment.
Legacy --pi-repo, --pi-dir, --pi-server-id and --pi-extension flags are retired.
Provider setup, missing/expired credentials and model refresh are documented in getting started. Data ownership, quitting, uncertain work and diagnostic privacy are in support and recovery. Review diagnostic output before sharing it: engine logs may contain secrets. For sensitive security concerns, use the private vulnerability-report route and security policy, not a public bug report.
| You want to | Run |
|---|---|
| Talk to a real model | scripts/run.sh (source build), or pipkin / the installed Mac app; configure the provider in Pipkin |
| Verify installed coding without live accounts | scripts/test-native-package.sh (isolated scripted provider, real tools, migration and restart) |
| Look around with fake data | pipkin --demo normal (also: jobs, followup, failure, unknown, stressed, large, persist-fail) |
| Check an installation | pipkin --version, pipkin --diagnose [--probe] |
| Open a specific project | --project DIR (repeatable; the last one is selected) |
| Use your own editor / terminal | --editor CMD, --terminal CMD (else $VISUAL/$EDITOR, $TERMINAL) |
| Keep data elsewhere | --data-dir DIR |
Type /goal <what to accomplish> in the composer and press Enter. While Pipkin is open, it keeps the goal attached to that conversation and asks the engine to continue after each completed turn until the engine explicitly reports it met, blocked, or unreachable. /goal <new goal> replaces it; /goal clear removes it and stops an active goal turn. The goal strip above the composer shows its status and has a clear button.
If the engine does not give an unambiguous status, or a turn fails, Pipkin pauses instead of blindly continuing. Saved goals return paused after a restart so an uncertain turn is never resent automatically; re-enter /goal <goal> to resume. In demo mode, replies are simulated and do not execute the goal.
Type /session in the composer, use Session usage in the command palette, or click Usage beside the composer to inspect the selected session. Pipkin reads the committed usage ledger and shows input/output/cache tokens, total tokens, reported cost, and a model/tool breakdown. The figures are the engine's estimates, not a provider billing balance. Demo mode reports no real usage.
The engine currently does not expose provider account quota, remaining balance, or reset times to Pipkin. Check your provider dashboard for account limits.
Ctrl K command palette |
Ctrl N new chat |
Ctrl L focus composer |
Ctrl J focus transcript |
Enter send |
Shift Enter new line |
Ctrl Enter queue follow-up |
Ctrl Shift Enter steer the run |
Ctrl . stop the run |
Ctrl M choose model |
Ctrl O attach files |
Ctrl Down jump to latest |
Ctrl B sidebar |
Ctrl I changes pane |
Alt Up/Down previous / next chat |
F2 rename demo chat |
Ctrl , settings |
Ctrl Shift O open project |
Esc close a menu |
Ctrl Q quit |
Real-mode conversation names are derived from prompts. The pinned engine has no rename operation: the palette entry is disabled and F2 explains the limitation, rather than claiming a local title is engine-confirmed.
flowchart LR
UI["pipkin-ui<br/>GPUI views, text editing,<br/>virtualised transcript"] -- Commands --> Core
Core["pipkin-core<br/>pure state machine<br/>(no GUI, no I/O)"] -- Effects --> App
App["pipkin-app<br/>controller, SQLite<br/>(drafts, journal, saved copies)"] --> Backend
Backend["Native adapter"] <-- framed stdio --> Engine["pipkin-engine<br/>private worker in the same binary"]
pipkin-coreholds every decision (run state, queues, availability, draft and save state) and knows nothing about the GUI. Every event from the engine carries(conversation, generation, operation)and stale ones are dropped.pipkin-uionly renders and turns input into commands. Rendering does no I/O and no parsing.pipkin-appowns the database, the launched engine's lifecycle and the glue. It starts/restarts the engine it owns and stops it when you quit. A separately started external server can continue work; see quitting and interrupted work.pipkin-engineruns providers, coding tools, durable sessions and queues;pipkin-engine-protocoldefines its versioned desktop boundary.
| Milestone | State |
|---|---|
| Real read path, first real workflow, daily-use execution and recovery | Built, tested against a real engine |
| Complete local product (history, search, tool output, offline cache) | Built; native gates partly run |
| Distributable alpha (bundled engine, package, diagnostics, upgrade / rollback) | Built; checked in a scratch prefix, not on a clean machine |
| 1.0.0 and 1.1.0 releases (Linux archive, experimental macOS builds, checksums) | Published; nothing but Arch / Omarchy is supported, and releases are not signed |
Not done or not verified yet: a screen reader does not yet speak typed characters in the composer; input methods
are verified with one engine; 150% scale, minimize / suspend / resume, a clean pacman -U install and a long soak are
for a person to run; macOS has experimental native builds but Windows remains deferred; there is no in-app update channel. The
owner-run checks are written up in docs/native-gate-testing.md and the full plan, with
what each milestone really covers, is in docs/rust-desktop-client-plan.md.
| Platform | Support |
|---|---|
| Arch / Omarchy, Wayland (Hyprland) | Supported (1.0.0) |
| X11 / Xwayland | Builds and starts; seen under Xwayland only |
| GNOME, KDE, other distributions | Unverified |
| macOS Apple Silicon / Intel | Experimental release builds (ad-hoc signed, not notarized); engine tests still intermittent on the macOS CI runners; interactive acceptance partial |
| Windows | Deferred (platform status) |
cargo test --workspace && cargo clippy --workspace --all-targets && cargo fmt --all --check
# Build and verify installed migration, coding tools and restart without live accounts
scripts/test-native-package.sh
crates/pipkin-core state machine, protocol of commands/effects (no GUI)
crates/pipkin-ui GPUI views, theme tokens, text editor, transcript
crates/pipkin-app controller, storage, engine lifecycle, install and diagnostics
crates/pipkin-engine native engine, providers, tools and durable store
crates/pipkin-engine-protocol versioned messages and transports
packaging/ scripts/ Arch package, installer, release and verification scripts
assets/ fonts, icons and the mascot, with provenance
docs/ the plan, architecture, packaging, platforms, beta and gate notes
Useful reading: docs/architecture.md, docs/packaging.md,
docs/platforms.md, docs/beta.md, docs/extensions.md,
docs/scorecard.md. The built-in engine conversion is tracked in
llm-docs/pipkin-rust-engine-plan.md; the built-in engine is now the default.
AGENTS.md lists the project's non-negotiables, including the safe way to
drive the real window in native tests (scripts/guard.sh).
Pipkin is built on GPUI (from the Zed project; Zed's GPL crates are read for
reference, never copied) and includes MIT-licensed behavior ports from Pi, with notices retained. Typeface: Poppins
(SIL OFL) for the interface, Lilex (SIL OFL) for code, IBM Plex Sans Italic (SIL OFL)
for emphasis. Icons: Lucide (ISC). The mascot and wordmark are Pipkin's brand artwork. Full
provenance is in assets/PROVENANCE.md.
Pipkin is released under the MIT License. The bundled fonts, icons and mascot keep their own terms, listed in
assets/PROVENANCE.md: Poppins, Lilex and IBM Plex Sans are SIL OFL 1.1, the icons are ISC, and the
mascot and wordmark are Pipkin's brand artwork, used as approved. No Pi engine is bundled: the built-in engine ports behavior
from Pi, and the notices for the ported Pi, Anthropic, minimatch and brace-expansion sources are kept in
packaging/upstream-notices.json and shipped in every archive's license inventory.



