pi-arc-caffeine
pi extension for Arc workspaces: stable skill paths and tool list, guidance on waiting for long-running work, and a guard against long sleeps
Package details
Install pi-arc-caffeine from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-arc-caffeine- Package
pi-arc-caffeine- Version
0.3.0- Published
- Nov 20, 2026
- Downloads
- 602/mo · 132/wk
- Author
- kyle-ganaz
- License
- unknown
- Types
- extension
- Size
- 18.6 KB
- Dependencies
- 0 dependencies · 1 peer
Pi manifest JSON
{
"extensions": [
"src/index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-arc-caffeine
A small pi extension for Arc workspaces that tells pi to sleep less. Add npm:pi-arc-caffeine to the workspace's pi packages;
there is nothing to configure. It does four things:
- Stable skill paths. Arc copies
/workspace/.piinto a new.pi/resources/snapshot-<random>/for every pi launch, so skills loaded from there get a new<location>in the system prompt whenever pi starts, and nothing after it can be read from the prompt cache. Each such skill is listed at the same file under$ARC_WORKSPACE_ROOT/.pi/skillsinstead (default/workspace), if it exists there. If an earlier extension already replaced the prompt, the same rewrite is applied to its text. - Stable tool list. Arc lists some tools' fields (such as a schema's
required) in a different order each time it starts pi. pi records that as a patch removing the tool and adding it back at the end of the list, so the provider's whole prompt cache misses. Patches that change nothing apart from key orrequiredorder are left out of each request. - Waiting guidance. The main session's system prompt gets a short section on waiting for long-running work: Arc's bash hands anything slower than 60 seconds to the background, and its result starts the agent's next turn, so the agent should end its turn rather than poll. Subagents and workflow agents, whose turn can't resume, don't get it.
- Sleep guard. A
bashcall whose command starts withsleep(after anycd … &&orcd …;) for longer than 5 seconds is refused. The model is told to end its turn to wait for a command it started (subagents and workflow agents aren't), or to run one bounded loop that exits on a condition, such astimeout 900 sh -c 'until <check>; do sleep 5; done'; a sleep inside a loop like that is allowed.
It also records, as an arc-extension-telemetry custom entry in the pi session file (never sent
to the model), whether each of its fixes had anything to change: at most twice per pi process,
the first time a fix changes nothing and the first time it changes something. tool_patches also
records each new reorder patch it drops, so the check can tell which requests it covered.
Workflow agents (sessions without a file) record nothing. Demeter's check-arc-prompt-cache
skill summarizes the entries, to show which fixes are still needed.
This is a subset of pi-arc-lifecycle, which
does all of the above and much more. Don't load both.
Development
pnpm i
pnpm test # vitest; never calls a model
pnpm type-check
pnpm format
To release, bump version in package.json in your PR. When it merges to master,
.github/workflows/publish-arc-caffeine.yaml stages it on npm with trusted publishing (OIDC,
GitHub environment npmjs-pi-arc-caffeine); a maintainer then approves it on npmjs.com (or
npm stage approve <id>) with 2FA. ./publish.sh is the manual fallback.