Open a Chat in cherry π and you meet Picache. Ask it to put your tests beside the code, find a result in another pane or help sort out a handoff. It works inside the same project layers and running desktop you do.

Picache is pronounced pee-KAH-cheh. The name belongs to the agent. The lowercase picache command is its set of hands: the workspace tools you can also use from a shell. That distinction explains a good deal about how Picache works.

At work in a layer

Say a test has failed in your API project. You can ask Picache to open a pane for the test run, read the output and show you the failure. The new pane belongs to that layer. Your editor, shell and other running panes remain where you left them.

Picache's conversation follows the layer, too. Switch to the website project and you get that project's Chat and folder; return to the API and its conversation is still there. You don't have to reconstruct the project from a pasted transcript each time you change tasks.

The work can become more involved. Picache can read files and pane output, search the workspace, arrange panes, run a command, or propose a change through the workspace's tools. It can write a short Lua script against those tools when several calls belong together. If a test needs repeated attempts, a coding loop keeps its steps and results in the Runs view. You can inspect what happened instead of relying on the last chat reply to describe it.

One path to the tools

There is no private shortcut from Picache's Chat to your files. A tool call goes to the same picache verb and handler as the command you can type yourself. The harness checks who made the call, which layer it concerns, the caller's grants and the call's effect. It may run, ask you or refuse. The outcome gets a receipt.

One registry, every way in Four callers reach the same verbs: you in a shell typing picache split, Picache making the split tool call in a Chat, a vendor agent typing picache split in its pane with its own token, and the same agent calling split as an MCP tool through picache mcp, with the same token. All go to one registry of 88 verbs, each with one handler, an effect class and a capability. The policy decides each call from the token's actor, the workspace's grants and a budget per token: it runs and the receipt names who called, or you are asked, at your terminal or in your client, or it is refused with the reason. For this split, yours runs, and the other three are asked. you, in a shell picache split -- make test Picache, in a Chat tool call: split {command} an agent in its pane picache split, its own token an agent over MCP picache mcp, the same token ONE REGISTRY 88 verbs one handler each an effect class a capability --json for programs THE POLICY, PER CALL who: the token's actor the workspace's grants a budget per token ✓ runs; the receipt names who ? asked: your terminal or client ✕ refused, and why THE SAME VERB, THE SAME CHECK, THE SAME RECEIPT · ONLY WHO IS CALLING DIFFERS
A verb takes the same path whoever calls it.

For example, opening a pane changes your desktop. Writing a file changes your project. Running a command may do more than either. Those are different requests, and Picache cannot turn a model's suggestion into permission just by asking confidently. When a call needs your decision, the client asks you; an unanswered question remains visible in Recovery rather than silently becoming approval.

This is also why the picache command matters beyond Picache itself. You can script the TUI with Lua, and an installed agent can call workspace verbs from its own pane or through MCP. The handler still sees that caller's identity. The Lua article shows a script opening a test pane, waiting for the real exit event and zooming the failure.

Working with other agents

Picache can sit beside Claude Code, Codex and other installed agents without taking over their conversations. Each vendor agent keeps its own harness and its own loop. Cherry Pi can host its pane, report when it is working or needs you, and give it scoped ways to communicate with the workspace.

Suppose one agent has a branch ready for review. Picache can send a message that names the work, follow the reply and put an issue or proposed change in the Inbox. A question sent to another layer is read-only there. A patch offered across that boundary waits for the receiving operator to accept it. Messages and offers have different effects, and their routes say who sent them.

Picache can also use a local model selected in the Models pane. Cherry Pi checks whether the model fits this machine, serves it as a job and runs inference away from the harness's main process. A model is a source of proposals and words; the workspace's tools and decisions remain with the harness and the operator.

When you come back

A useful assistant has to leave more than a convincing answer. Picache's Chat belongs to the layer. Tool calls have outcomes you can inspect, jobs and loops have records, and an interrupted changing operation can leave an explicit Recovery item if its result is uncertain. Returning to the project means returning to its work, not starting from an empty prompt.

Try Picache first on something you can see: ask it to arrange a pane, inspect a test result or find a file in the current layer. Watch where it asks, where it acts and what it records. The manual lists the commands and the harness article explains how Picache fits beside other agents.