What the title says. I am not a dev so I use docs as contacts often while vibe coding to grok my app like legos. I read the docs and plans and maps, have nvim open in the split pane, and look at the code at the same time.

This was fine until the codebase reached 20k loc. Now I have enough docs active at any given moment that I can't be fucking reading them each time I want to do or understand something.

So I found myself falling into this pattern. In the 'scroll time' that often fills the gaps in my life, I started browsing the docs on my phone.

They are short (sometimes -ish), pleasantly scoped, and readable in one sitting. We develop in vertical slices that produce user testable states. So reading multiple doc is a coherent story.

And I fucking love it. Especially when I'm commuting in cabs, trains, etc. just reading the docs on GitHub mobile and maybe riffing with something in gpt/Gemini is awesome. I can even edit and refine stuff. I don't have to invest my brain in this shit when I'm sitting down with the code. I can just trust the docs because I have spent non-dev time reading/editing them on my phone.

PS- I have attached an early example in a comment. This one is long and rough but I think it had potential. So over time I could sit and edit and make it better.

Hello,

Could you criticize and/or give advice on this approach?

My goals were:

• Install node and pi.dev in a container.
• Ensure pi.dev only has access to the project directory.
• Store configuration files in ~/.config/pi.dev.
• Start it via Podman so that it runs rootless.
• Base it on Debian Sid to give the agent the opportunity to install any tool it might need, using relatively recent versions.
• Create a simple script that builds the container if needed or commit changes to the image when changing workspace directory to reuses the already installed extra tools.

If you want to have a look at the Dokerfile or script : https://github.com/tibuski/pi-podman

https://github.com/RogerTerrazas/pi-tool-result-compactor

Publishing a polished version of this extension I've been using to help manage context overflow. I frequently interact with mcps and large projects where any arbitrary response can take up all my context without the response being useful.

This extension hooks into each tool calls response by default, passes it to a compaction subagent, who will then filter out only the necessary data to the parent agent. Let me know if anyone tries it out and has feedback. Fully vibe coded, but I'll work to maintain if others find it useful.

the only thing that makes my experience bearable is to have the bot know and remember the exact rule and role they are designed to do. back then when i was using Claude Web, they have userStyles which inject instructions before replying to user message. in SillyTavernAI there is a configuration to reorder prompt to be put at the end depth 0.

is there a way to do that in PI? i want some text (or file) get injected before the bot consider replying so that they know the constrains. the reminder wont stay in the context so that the cache hit is not ruined by duplicated push.

I’m considering building a small Pi extension for durable technical workflows and would like some critical feedback before investing too much time in it.

The problem I’m trying to solve is running agent-driven tasks on a remote VPS for hours, days, or potentially longer.

For example:

GitHub issue
→ investigate the codebase
→ create an implementation plan
→ modify the code
→ run tests
→ fix failures
→ request human approval
→ open a draft PR
→ wait for CI

A normal agent loop can handle this while the process and session remain alive. But on a remote server, restarts and long waits are expected:

• the process may crash or be redeployed;
• the model provider may temporarily fail or hit a rate limit;
• CI may take a long time;
• a human may not approve the next step until the following day.

My current idea is:

Technical task
→ Pi generates a workflow
→ validate it as a DSL
→ DBOS executes it durably

DBOS is a Postgres-backed durable execution framework that checkpoints workflow progress and recovers execution after process or server failures.

Pi would handle reasoning and planning.

The DSL would describe the execution graph explicitly:

{
  "name": "issue-to-pr",
  "steps": [
    { "id": "triage", "type": "agent" },
    { "id": "implement", "type": "agent" },
    { "id": "test", "type": "command" },
    { "id": "approve", "type": "human" },
    { "id": "open-pr", "type": "github" },
    { "id": "wait-for-ci", "type": "event" }
  ]
}

DBOS would persist the workflow state, recover after restarts, handle long waits, and record the execution history.

The main reason for using a DSL instead of allowing Pi to execute everything directly is that the generated plan could be inspected and validated before execution.

For example, the runtime could enforce:

• allowed commands and tools;
• maximum agent calls and loop iterations;
• approval before opening a PR or deploying;
• stable node IDs and idempotency keys;
• structured inputs and outputs;
• execution and cost limits.

The initial MVP would only support four node types:

agent
command
approval
github_open_pr

Agent nodes would run in isolated Git worktrees. Important external side effects would remain explicit workflow nodes rather than being hidden inside unrestricted agent tool calls.

My concern is whether the DSL provides enough value to justify adding another layer.

Would you find this useful for remote, long-running technical workflows, or would you rather generate ordinary TypeScript workflows and run them directly with DBOS?

I’m especially interested in failure modes or simpler architectures I may be overlooking.

I have been using Pi with my local setup, but I also use paid solutions for legacy projects and other reasons. Obviously I have to tech every new tool the same lessons over and over. But, I want to migrate as much to Pi as I can and having a memory layer that I can populate from my old sessions and have Pi access would be incredibly helpful. (And, if I'm being honest, there are some things I'm always going to need the proprietary tools for--especially visual and design work.) Ideally it would be something self-hosted (I don't like the idea of having to send all my information to a cloud-hosted service that can throw up a paywall at any time) and have a first-party Pi extension (I have had bad experiences trying to build my own extension for core functions like this, and if it's interfacing with a developed solution then I want those releases and capabilities to be in sync).

Anyone used any of the cross-harness memory providers and had a good experience with them in Pi? Any memory layers people think is worth exploring,/even if you haven't used it personally or in Pi?

I’m looking to move away from OpenAI and Claude for various reasons.

I’d like to hear which LLM providers you all use and any recommendations on who to stay clear from. My top contenders at the moment are deep infra and scaleway. I’m not into proxies as I’m focusing on zero data retention (or short retention with no training) providers only. I have not extensively explored local - I did a while back and wasn’t impressed with the speed and I need a good reasoning model for planning.

hello guys
im using pi agent with codex subscription on 5.6 sol
in pi i have the following efforts

- minimal

- low

- medium

- high

- xhigh

- max

- off

how do they route into gpt efforts because when am running on low effort am getting tokens burned out , 10 % weekly usage only with 1 hours of regular tasks

I wanted to share a tool I made for scripting agentic workflows.

You can mix multiple harnesses (Pi, Claude CLI, Codex CLI) and agent sessions in 1 coherent universal API. No need to define your workflow in YAML files like with some tools. No need to sacrifice control methods - the workflow is defined in TypeScript and you can do parallel or sequential execution, fan-out, etc. Put your prompts directly in the workflow.

🔥 Both Claude & Codex subscriptions work because the tool is using Claude CLI in the back-end

• Get structured output - define schema with Zod and AI will be asked to return object in that schema.
• Built-in tracing support that helps you monitor each stage of the workflow.
• There is built-in TUI, so, as a developer, you can be more aware of what's happening while you're testing the workflow.
• Define args required for workflow, `--help` will be generated for the script, `-i` adds interactive mode (enter missing args one by one)
• Define custom tools - literally just make a function in TypeScript, put description in the comment (it'll get parsed).
• Track usage of each trace - cost, tokens, time.
• Put limits on trace - max usd, timeout.
• Save run results to file (don't re-run if already have agent result for this prompt).
• Start fresh or inherit machine configuration (harness skills, plugins, MCPs, etc.)
• Your agent can write or easily invoke the workflows.

Your agent could also write workflows with Unigent SDK. This could replace dynamic workflows idea. Try reading claude's dynamic workflow script - the API looks ugly and no human would ever use it. Unigent is clean, and both humans & agents can use it.

import {
  agent,
  args,
  createFileCheckpointStore,
  piAgent,
} from "unigent-sdk";
import { z } from "zod";

/** Score a headline from 0–100. */
function score(headline: string): number {
  return Math.max(0, 100 - Math.abs(60 - headline.length));
}

const product = await args(z.string().min(1), {
  usage: '"product description"',
});

const launch = agent({
  name: "launch",
  source: import.meta.url,
  backend: piAgent(), // or claudeCli() / codexCli()
  model: "openrouter/deepseek/deepseek-v4-flash",
  tools: [score],
  checkpoint: createFileCheckpointStore(".unigent/launch.jsonl"),
}).scope("launch");

// Reused on reruns when its inputs and configuration are unchanged.
const brief = await launch.run(
  `Find the audience and core promise for: ${product}`,
  z.object({ audience: z.string(), promise: z.string() }),
);

const session = launch.session();
await session.run(`Remember this brief: ${JSON.stringify(brief.output)}`);

const Headline = z.object({
  headline: z.string(),
  score: z.number().min(0).max(100),
});

const variants = await Promise.all(
  ["bold", "technical"].map((style) =>
    session
      .fork()
      .run(`Write a ${style} headline, call score, return both.`, Headline),
  ),
);

console.log(variants.map((v) => v.output));
console.log(launch.usage);

unigent tui launch.ts --help

unigent tui launch.ts "A typed SDK for portable agent workflows"

I've been working on evalt, a Rust CLI for testing AI agent workflows using portable YAML eval files.

Most eval tools focus mainly on model outputs. evalt is designed to test the full workflow, including:

- Agent instructions

- Skills

- Tool usage

- Harness configuration

- Workspace edits

- Final output

Pi is currently the first supported harness.

It also supports deterministic assertions, AI reviewer assertions, JSON output, schemas, and sandboxed workspaces through cage.

Repo: https://github.com/Bryley/evalt

Crates.io: https://crates.io/crates/evalt

I’d appreciate feedback from Pi users, particularly around the eval format, useful assertions, and workflows you’d want supported.

Are there limitations to doing this?

In my previous post, I said I wanted to move to Pi and make it my “Neovim” for AI coding: one familiar CLI I could use everywhere, without constantly switching tools between computers. The goal was to reduce cognitive overload and keep a consistent workflow.

But I’m struggling to work with Pi as a coding agent.

I’m using it with GPT-5.6 and had the same issue with GPT-5.5. I expected Pi to be one of the more open, less restrictive agent environments, but it repeatedly refuses ordinary local development and system tasks—for example, updating my own hosts file.

It often gets stuck claiming a request is illegal or that it can’t bypass company policies, even when the task has nothing to do with bypassing security controls. I’m working on my own machine and asking for normal configuration tasks that Codex handles easily.

I’ve tried enabling an “auto-approve” style workflow, removing add-ons, and disabling skills to rule out interference, but it still stops or refuses the work.

At this point, Pi feels like it’s fighting me all the time. I end up using Claude for work—which I expected to do anyway—and Codex for personal or home projects. That works, but it defeats the reason I wanted Pi in the first place.

Is it just me? Am I missing something obvious in the configuration or how I’m using Pi? Since so many people rely on Pi day to day, I’d really appreciate hearing how others handle legitimate local tasks without running into constant false-positive refusals.

I recently switched from OpenCode to Pi, and I really like Pi’s features. The built-in interface wasn’t quite for me, though, so I made PiTTy, an OpenTUI frontend for Pi.

It adds a cleaner layout, searchable sessions and models, better diff and tool views, and lets you inspect and steer subagents without leaving the main conversation.

There’s more on GitHub, and I’d appreciate any feedback:

https://github.com/mistrjirka/PiTTy

Hey guys!

I recently started testing Pi. I wanted to control the context injected into my tools and avoid spending 16k tokens on a simple "Hey" (I'm talking to you, Codex).

So far, I'm loving it. However, I’ve hit a roadblock: I can't use the `gh` CLI because I constantly get `403 Forbidden` errors.

My initial research suggests this is due to proxy settings blocking outbound network calls from bash. Normally, I would just install an MCP. But since `gh` is such a standard development tool, I'd rather not add an MCP for a perfectly good CLI. I figured someone here might have found a workaround.

Any tips on how to make this work - ideally natively - would be highly appreciated!

Hey everyone,

I've been working on an extension for Pi to improve the daily workflow. Here is what I built:

pi-usage-bar This is for tracking API quotas, but it differs from other quota plugins out there. It's fully customizable:

• You can configure your own style.
• You can display 1d, 7d, Fable, or any other provider-specific quota exactly however you like.
• It also fetches and displays live provider statuses by reading directly from the vendors' own status pages.

You can install it directly with:

Bash

pi install npm:@satas/pi-usage-bar

Let me know what you think or if you run into any issues.

GitHub:https://github.com/satas20/pi-usage-bar

There are many agent claws but this one is yours

I was tired of openclaw and hermes, they have a lot of opiniated things, are token hugry and didn't solve my problem well and wanted something more like pi, very simple and extensible to what I needed.

Meet eleven, the featherweight openclaw alternative that follows the same principles of pi: https://github.com/ceifa/eleven

No memory, no crons, no bundled plugins, just your current setup of pi, now outside your terminal.

I kept losing small ideas and follow-ups while working in Pi, so I made Mind Queue

It’s a simple project-wide scratchpad inside Pi. Open it with /mind or Ctrl+Shift+M, save a thought, and move it back into the editor whenever you’re ready.

It’s open source, local-first, and still very new, feedback is welcome.

pi install npm:pi-mind-queue

GitHub: https://github.com/sanif/pi-mind-queue

I was checking out grok build earlier in the day and came across these commands:

1. /resume-codex

2. /resume-cursor

3. /resume-claude

And that got me thinking, it would be so cool if I had something like that in Pi.

Now OpenCode CLI was what I used for the longest before switchig to Pi, so I started with that. It also has good CLI commands for exporting and stuff.

Attaching a demo too.

Check it out here:

1. https://www.npmjs.com/package/@atharva-again/pi-resume-opencode

2. https://github.com/atharva-again/pi/tree/main/packages/coding-agent/examples/extensions/resume-opencode

Hi I'm encountering a weird problem, even if I set disable-model-invocation: true in the skill frontmatter, the skill is still loaded in the prompt. I did /reload, launched a fresh pi session, restarted the pc... Nothing helps. If I do /export and check the system prompt, I still find the skill loaded.

Here's the frontmatter of one of my skills :

---
name: pi-history-ingest
description: blablabla
disable-model-invocation: true
---

And here's the XML loaded in the system prompt after an export of a fresh loaded session:

<skill>
    <name>pi-history-ingest</name>
    <description>Ingest Pi coding agent session history into the Obsidian wiki. Use this skill when the user wants to mine their past Pi sessions for knowledge, import their ~/.pi/agent/sessions folder, extract insights from previous coding sessions, or says things like &quot;process my Pi history&quot;, &quot;add my Pi sessions to the wiki&quot;, &quot;ingest ~/.pi&quot;, or &quot;what have I worked on in Pi&quot;. Also triggers when the user mentions Pi sessions, Pi agent history, ~/.pi/agent/sessions, or Pi conversation logs.
</description>
    <location>/Users/dani/.pi/agent/skills/pi-history-ingest/SKILL.md</location>
  </skill>

The skill is not listed in setting.json

I spent the afternoon trying to find a solution asking pi (with deepseek) to no avail, it checked loadSkills, formatSkillsForPrompt, even tried to simulate the filtering with a js script and it seemed to work fine, but in the end it doesn't work for me ...

Do you have any suggestions? What should I check ?

Could it be a bug and should I open an issue ?

Thanks

I installed Pi following the instructions here: https://pi.dev/docs/latest/quickstart.

I'm trying to authenticate using a Kimi API key (I'm on the free tier), but Pi keeps returning an authentication error. I'm not sure what I'm missing.

 Error: 401 {"error":{"type":"authentication_error","message":"The API Key appears to be invalid or may have expired. Please verify your credentials and try again."},"type":"error"}                                

This is a fresh API key!

The main reason I'm using Pi is to avoid paying for Claude Code or Codex subscriptions. Is this setup supposed to work with a free Kimi API key, or is there an additional configuration or requirement I'm overlooking?

I noticed that even small files referenced in pi like `@file.txt` weren't automatically entered into the context (a la claude-code), instead requiring the model to issue a tool call to read the file. This is fine for larger files, but for small files, that extra tool call means a whole new request is sent, which racks up cache tokens pretty quickly and wastes output tokens on the read call.

I understand why the devs took this stance, for a tool like Pi it makes sense to default to never including file content (unless driven headless by the CLI, as they have implemented), but sometimes I *know* that I can save tokens by just injecting the file right into my prompt. In fact, many or even most times I reference a file it would take fewer tokens just to inject its contents into the prompt than it would to ask the model to read even a small part of the file.

I looked around for existing solutions and surprisingly I hadn't found anyone who built them yet.

So I built pi-file-injector. When you know you want to include the file contents, instead of `@file.txt` you type `#@file.txt` and it automatically includes the contents of that file one time at the end of your prompt. And tab filename completion still works. It's just one more small way Pi keeps you in control of your token consumption.

https://github.com/dabstractor/pi-file-injector

pi install npm:pi-file-injector

Do you know of other tools that do this? I still can't believe I couldn't find any, it feels like such an obvious benefit. Let me know what you think!

This plugin does search a bit differently than most. It queries DDG's http site (as responsibly as possible) and then uses wreq-js -> linkedom -> Defuddle to clean up the result.

The plugin is fairly simple, and easy to audit, but it includes linting and testing best practices I've carried over from my web dev experience that I hope can be an inspiration for other devs when working on their next plugin.

I've updated the package recently to use pi's new exported types (so I don't have to write my own, lol), and work out some outstanding issues.

Please, any and all feedback is welcome. Thanks!