I built a simple Markdown system that helped me waste way fewer tokens

Rodrigo Pena — Sat, 05 Sep 2026 03:30:22 +0000

A while ago, I started noticing the same thing happening in almost every AI coding session.

At first, everything felt great.

I’d open Cursor, Claude, or Windsurf, explain what I wanted to build, and within minutes the AI would be helping with endpoints, components, utilities, bugs… the usual magic.

But after a while, things would start getting really messy.

My agent would forget decisions we had just made. It would bring back a library I had already decided not to use. It would rewrite something that was working. Or worse: I’d spend a few prompts fixing a bug, only for that same bug to quietly come back later.

And every time that happened, I had to explain the project all over again.

The architecture. The stack. The conventions. What was off-limits. What we had already tried.

That meant more tokens, more vague responses, more rework, and a lot more frustration than I expected.

So I started thinking: maybe the problem isn’t that AI coding tools can’t generate code fast enough.

Maybe the real problem is that they don’t have a reliable way to stay grounded in the project.

That idea eventually became PXOS.

The problems I kept running into

These were the patterns that kept showing up for me:

The AI would forget important architectural decisions halfway through a task.
It would touch files that had nothing to do with the request.
It would start writing a lot of code before really understanding the problem.
I’d waste a huge amount of context re-explaining the same project details.
If I opened multiple agent sessions, they could end up stepping on each other’s work.

None of this means the models are bad. They’re incredibly useful.

But I realized that, if I wanted AI agents to be genuinely helpful on larger or longer-running projects, I needed a better workflow around them.

My first instinct was to overcomplicate it

Like a lot of people, I initially thought I needed a smarter orchestration layer.

I experimented with local RAG setups, Python services running in the background, vector databases, multi-agent frameworks, containers… all the things that sound exciting until you’re the person maintaining them.

It quickly became too much.

Background processes crashed. Config got messy. API keys and environments became another thing to worry about. I was spending more time managing the AI tooling than actually building the product.

So I stepped back and asked a much simpler question:

What if the AI doesn’t need another complicated system around it?

What if it just needs clear instructions, project context, and decisions that live inside the repository?

That’s the idea behind PXOS.

What PXOS actually is

PXOS is a lightweight, Markdown-based operating system for AI-assisted development.

There are no background servers, no vector database, and no heavy runtime dependencies. It lives directly inside your repository in an .ai/ folder:

your-project/
├── .ai/
│   ├── AI_BASE.md          # Rules, boundaries, and autonomy levels
│   ├── PROJECT_CONTEXT.md  # Stack, architecture, conventions, and invariants
│   ├── CURRENT_SPEC.md     # Current task, requirements, and acceptance criteria
│   └── DECISION_LOG.md     # Important decisions made along the way
└── ... your actual codebase

Instead of hoping the model remembers everything from a long conversation, the important context becomes part of the project itself.

It is readable by humans, easy to version with Git, and available whenever you start a new AI session.

How I use it

PXOS gives the agent a simple workflow to follow:

Discover → Plan → Execute → Validate → Review → Compact

In practice, that means:

Discover: Before changing anything, the agent reads the project context and checks the relevant existing code.
Plan: It says what it wants to change and identifies whether the task is low-risk or needs approval first.
Execute: It makes focused changes instead of rewriting half the codebase.
Validate: It checks its work with tests, linting, builds, or runtime evidence.
Review: It looks for UX issues, missing states, and obvious gaps before calling the task done.
Compact: At the end, /compact summarizes what happened and saves meaningful decisions into the project’s decision log.

The goal is not to make AI agents rigid or slow.

It’s to stop them from drifting away from the actual project.

Running more than one agent

One of my favorite parts is how PXOS handles parallel work.

If I want two agents working at the same time, I don’t leave both of them editing the same folder. PXOS uses native Git worktrees to isolate each task:

pxos task feature/auth-redesign

That creates a separate workspace for that task, such as:

.worktrees/feature-auth-redesign

So one agent can work on authentication while another works on a dashboard or a bug fix, without both changing the same files and creating unnecessary merge conflicts.

It’s a small thing, but it has made parallel work much less stressful for me.

What happened when I benchmarked it

I set up a small benchmarking environment to compare raw AI-agent sessions against PXOS-guided sessions on the same multi-step tasks.

These are the results I got:

Metric	Unconstrained agents	PXOS-guided agents	Difference
Total tokens consumed	421,450	83,120	-80.3%
Architectural rework	44.1%	0.0%	Eliminated in this test
Out-of-scope file changes	7 files	0 files	Eliminated in this test
Multi-agent collisions	3 merge conflicts	0	No collisions in this test

The biggest improvement wasn’t just token usage.

It was how much calmer the workflow felt.

I spent less time correcting the AI, less time repeating context, and less time trying to understand why something unrelated had suddenly changed.

PXOS is still evolving, and these are results from my own controlled tests — not a universal promise for every model, project, or workflow. That’s exactly why I want more people to try it.

Try PXOS

You can install it in a project in a few seconds.

Python / PyPI

pip install pxos
pxos init

Windows / PowerShell

irm https://raw.githubusercontent.com/madebypx/PXOS/main/install.ps1 | iex

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/madebypx/PXOS/main/install.sh | bash

After that, start a session in Cursor, Claude, Windsurf, or another coding agent and say:

Read .ai/AI_BASE.md and .ai/PROJECT_CONTEXT.md before doing anything.

That alone already makes a noticeable difference.

A personal request

I built PXOS because I genuinely wanted a calmer, clearer way to work with AI while building real products.

A lot of late nights, experimentation, design work, and care went into it — including the website, which I’m admittedly very proud of.

So, if you have a few minutes, I’d really appreciate three things:

Visit the website: pxos.madebypx.com

I designed and built it with a lot of care. The CRT/terminal direction, the interactions, and the live telemetry concept were all part of making the project feel like more than just another CLI tool. And, modesty aside, I think it turned out pretty beautiful.
Actually test PXOS: Try it on a real task, a side project, or a feature you’re currently building. Then tell me honestly what worked, what felt confusing, what broke, and what you think is missing. Positive feedback is great, but constructive criticism is even more useful.
Run /benchmark after using it for a while: After one or two real sessions with PXOS, run:

   /benchmark

Or:

   pxos benchmark

The command asks for your consent before sending anything. If you opt in, it sends only anonymous numeric metrics — such as token usage, rework ratio, and task-completion signals — to the public research dashboard.

Those real-world metrics will help me understand whether PXOS is genuinely improving workflows across different projects, models, and setups.

🌐 Website: pxos.madebypx.com
🐙 GitHub: madebypx/PXOS
📊 Benchmark report: View the empirical report

If you try it, I’d love to hear how it went — especially what PXOS got right and where it still gets in your way.

DEV Community: Rodrigo Pena